chore: version packages (1.33.2)

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

.claude-plugin/marketplace.json

@@ -0,0 +1,30 @@
+{
+  "name": "codeman",
+  "owner": {
+    "name": "Ark0N",
+    "url": "https://github.com/Ark0N"
+  },
+  "description": "Codeman, self-hosted mission control for AI coding agents. Ships the codeman agent skill: let one Claude Code session spawn, prompt, wait on and read other sessions.",
+  "plugins": [
+    {
+      "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.33.2",
+      "author": {
+        "name": "Ark0N",
+        "url": "https://github.com/Ark0N"
+      },
+      "homepage": "https://getcodeman.com",
+      "category": "productivity",
+      "keywords": [
+        "codeman",
+        "orchestration",
+        "multi-agent",
+        "session-manager",
+        "tmux",
+        "claude-code"
+      ]
+    }
+  ]
+}

.dockerignore

@@ -0,0 +1,21 @@
+.git
+.agents
+.claude
+.codex
+# `**/` matters: a .dockerignore pattern is matched against the WHOLE
+# context-relative path, so a bare `.env` excludes ONLY the root file and
+# `COPY . .` would bake docker/.env -- CODEMAN_PASSWORD and any provider API
+# keys -- into the published image at /opt/codeman/docker/.env (verified).
+**/.env
+**/.env.*
+!**/.env.example
+# Same shape: docker/docker-compose.override.yml is the documented home for
+# host-specific settings, so it must not ride COPY . . into the image either.
+**/docker-compose.override.*
+node_modules
+dist
+coverage
+out
+test-results
+tmp
+*.log

.github/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing to Codeman
+
+Thanks for wanting to help! Codeman is a small project with a fast loop: issues usually get a response within a day, good PRs get reviewed quickly, and every release credits its contributors and bug reporters by name in the release notes. This guide gets you from clone to merged PR without stepping on the traps.
+
+## The short version
+
+1. **Bugs**: open an issue with your OS, install method (installer / npm / git clone), browser, and which CLI + version the session was running.
+2. **Questions and ideas**: use [Discussions](https://github.com/Ark0N/Codeman/discussions), not issues.
+3. **Small fixes** (docs, typos, a new skin, a translation): just send the PR.
+4. **Anything bigger**: open an issue or Discussion first and get a nod before building. Codeman has strong architectural invariants, and a design chat up front is what turns a big idea into a merged PR instead of a stalled one. This flow works: features like Clone Repo (#236) went idea, then design discussion, then review, then shipped.
+5. **Security issues**: never a public issue. See [SECURITY.md](SECURITY.md).
+
+## Dev setup
+
+Requirements: Node.js 22+ (see `.nvmrc`), tmux, and at least one supported agent CLI on your PATH (Claude Code is the primary one).
+
+```bash
+git clone https://github.com/Ark0N/Codeman.git
+cd Codeman
+npm install        # postinstall builds the vendored xterm addon bundles
+npm run dev        # dev server on http://localhost:3000
+```
+
+The frontend is plain JS served from `src/web/public/` with no bundler in dev: edit a `.js`/`.css` file and reload the page. The one exception is `index.html`, which is read once at server start, so markup changes need a server restart.
+
+## Before you push
+
+CI runs all of these, so save yourself a round trip:
+
+```bash
+npm run typecheck               # tsc --noEmit, strict mode
+npm run lint
+npm run format:check
+npm run check:frontend-syntax   # syntax-checks the plain-JS frontend modules
+npm run check:browser-excludes  # every browser-driven test is kept out of `npm test`
+```
+
+`npm install` also installs a `pre-push` git hook that runs these static checks (about 10-40s, machine-dependent) and blocks the push if one fails. It skips itself when you push something other than the checked-out HEAD, or when the tree has uncommitted changes the checks would read. Skip it once with `CODEMAN_SKIP_PREPUSH=1 git push`; it never replaces a `pre-push` hook of your own.
+
+### Tests
+
+```bash
+npm test                          # the gate — exactly what CI runs
+npm test -- test/<file>.test.ts   # one file
+```
+
+`npm test` is the same suite CI runs, so a green run locally means a green run there. It leaves out three suites that cannot pass on an arbitrary machine, each with its own command:
+
+```bash
+npm run test:browser   # Playwright + chromium (+ a live server; codex-predictive-echo needs a real codex binary)
+npm run test:mobile    # the above plus environment-specific PNG baselines
+npm run test:perf      # wall-clock benchmarks — run on an otherwise idle machine
+npm run test:all       # literally everything, environmental failures included
+```
+
+Expect `test:browser`/`test:mobile`/`test:perf` to fail where the machine cannot provide what they need; read that as "not runnable here", not as a regression. `config/test-suites.ts` holds the globs, and both configs derive from it, so the exclusions and those runners cannot drift apart.
+
+If you add a test that binds a port, pick a unique one at 3150 or above (search the repo for `const PORT =` first). Never 3000.
+
+Tests are tmux-safe by design: under vitest, the tmux layer becomes an in-memory mock, so tests cannot touch real sessions.
+
+## Finding your way around
+
+- Every source file starts with a `@fileoverview` JSDoc block. Read it before diving into the file, it is the map.
+- [`CLAUDE.md`](../CLAUDE.md) at the repo root is the densest architecture primer in the repo. It is written for AI coding agents, but the invariants and gotchas in it apply to humans exactly the same, and most review feedback on PRs traces back to something already written there.
+- Deep mechanisms and the history behind each rule live in [`docs/architecture-invariants.md`](../docs/architecture-invariants.md).
+- Third-party extension surfaces are documented in [`docs/extending-codeman.md`](../docs/extending-codeman.md).
+
+## Great first contributions
+
+These are well-fenced areas where a first PR is genuinely easy to get right:
+
+- **A new theme skin.** A skin is four things kept in sync: the `html[data-skin="…"]` token block in `styles.css`, the xterm ANSI palette in `terminal-ui.js`, the pre-paint allowlist and the settings picker (both in `index.html`). `test/skin-themes.test.ts` statically checks the sync, so if the test passes, your skin works.
+- **A new language.** `src/web/public/i18n.js` is dependency-free, English is the canonical source, and `zh-CN` is a complete example to copy. Add your language's entries and register it in `SUPPORTED_LANGUAGES`.
+- **Docs.** If you got stuck on something and then figured it out, the sentence that would have unstuck you is a PR.
+- Anything labeled [`good first issue`](https://github.com/Ark0N/Codeman/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
+
+Bigger extension points worth discussing first: new CLI backends (the pluggable resolver pattern has absorbed six CLIs so far; `docs/extending-codeman.md` and `docs/opencode-integration.md` show the shape), and real-device testing reports, especially mobile, which always find things emulation cannot.
+
+## PR expectations
+
+- **One change per PR.** Small and focused reviews fast; a grab-bag stalls.
+- Target the `master` branch.
+- **Keep your branch mergeable.** A PR with conflicts silently gets no CI runs at all (GitHub quirk), so rebase or merge master when conflicts appear.
+- Include or update tests when you change behavior. Route handlers have a lightweight pattern in `test/routes/` using `app.inject()` (no live server needed).
+- Formatting is Prettier with a deliberately narrow scope (`npm run format`), several frontend files are hand-formatted on purpose and excluded via `.prettierignore`. Don't "fix" a file by adding it back into Prettier's scope.
+- Don't bump versions or touch `CHANGELOG.md`; releases are handled by the maintainer via changesets after merge.
+- AI-assisted contributions are welcome (much of Codeman is built that way), with one condition: you must understand what you're submitting and have actually run it. "The model said it works" is not a test.
+
+## Conduct
+
+Be kind, be direct, assume good faith. Report unacceptable behavior privately via the contact in [SECURITY.md](SECURITY.md).

.github/SECURITY.md

@@ -69,10 +69,18 @@ shared-host, multi-user, or tunneled deployments.
 - **Multi-instance tmux socket is process-wide.** Two Codeman instances on the same `CODEMAN_INSTANCE` share a tmux socket and can attach each other's live sessions — isolate with distinct `CODEMAN_INSTANCE` values.
 - **The live log-tail route reads `/var/log` and `~/logs`** in addition to the session working directory (read-only) — a deliberate choice for tailing system/app logs. On a password-protected remote deployment an authenticated user can therefore read those roots outside their session. See `docs/security-architecture.md` §5.
 
-Recent hardening (this release): web-push subscription endpoints are restricted
-to https public hosts (SSRF guard — rejects internal/metadata IPs, validated at
-subscribe and send time), and tmux session names discovered on the shared socket
-are validated against the safe-name pattern before reaching any shell call site.
+- **The web-tab proxy fetches from the server's network position.** Any authenticated user can save a dashboard URL on loopback or a private range and have Codeman relay to it; that is the feature. Link-local and cloud-metadata addresses are the only refused targets (see below). On a shared host, restrict who holds an account.
+
+Recent hardening (2026-09-04): the web-tab proxy, its "Test" probe and its
+WebSocket relay refuse link-local and cloud-metadata targets (`169.254.0.0/16`,
+`fe80::/10`, `fd00:ec2::254`, `168.63.129.16`, `100.100.100.200`,
+`metadata.google.internal`), judged on the RESOLVED address so a DNS name pointing
+there is refused too; proxy capabilities are revoked on logout, admin logout and
+user deletion; proxied responses carry `Referrer-Policy: same-origin`. Earlier:
+web-push subscription endpoints are restricted to https public hosts (SSRF guard,
+rejects internal/metadata IP literals, validated at subscribe and send time), and
+tmux session names discovered on the shared socket are validated against the
+safe-name pattern before reaching any shell call site.
 
 For the detailed rationale, defenses, and recommended secure setups, see
 [`docs/security-architecture.md`](../docs/security-architecture.md).

.github/workflows/ci.yml

@@ -34,9 +34,127 @@ jobs:
       - name: Frontend JS syntax check
         run: npm run check:frontend-syntax
 
+      # Asks `vitest list` what CI would actually collect, rather than matching
+      # filenames: a browser-driven test missing from BROWSER_TEST_GLOBS
+      # (config/test-suites.ts) passes locally and dies in the test job with
+      # "browserType.launch: Executable doesn't exist".
+      - name: Browser-test exclusion check
+        run: npm run check:browser-excludes
+
       - name: Format check
         run: npm run format:check
 
+      # install.sh reaches users through `curl | bash` with nothing between it and
+      # them, and until now nothing in this repo checked it at all: no shellcheck,
+      # no bats, and the vitest gate is Node-only.
+      - name: install.sh syntax
+        run: bash -n install.sh
+
+      # macOS ships bash 3.2 and this runner has bash 5, so the constructs that
+      # actually break a Mac install are invisible here without a container. This
+      # step is what catches them — in particular expanding an EMPTY array under
+      # `set -u`, which bash 3.2 treats as an unbound variable and `bash -n`
+      # cannot see because it is a runtime error, not a syntax one.
+      - name: install.sh runs on bash 3.2 (macOS's version)
+        run: |
+          set -euo pipefail
+          docker run --rm -v "$PWD":/w -w /w bash:3.2 bash -n /w/install.sh
+          docker run --rm -v "$PWD":/w -w /w -e CODEMAN_INSTALL_SH_LIB=1 bash:3.2 bash -c '
+            set -euo pipefail
+            . /w/install.sh
+            detect_all_clis
+            # `shell` declares no binaries, so its offset/length window is length 0.
+            # Iterating it is the empty-array case; reaching here means it did not abort.
+            echo "bash $BASH_VERSION: ${#CLI_IDS[@]} CLIs, $CLI_FOUND_COUNT found"
+            cli_catalog_names >/dev/null
+            cli_catalog_print_install_hints >/dev/null
+            # The install menu with nothing installed and the user answering "s":
+            # skipping must warn and continue, never trip the "failed to install"
+            # gate (it did once, aborting the install before the clone).
+            has_tty() { return 0; }
+            headless_guard() { return 0; }
+            read_reply() { eval "$1=s"; }
+            NONINTERACTIVE=0
+            k=0; while [[ $k -lt ${#CLI_ALL_BINS[@]} ]]; do CLI_ALL_BINS[$k]="no-such-cli-$k"; k=$((k + 1)); done
+            k=0; while [[ $k -lt ${#CLI_ALL_PATHS[@]} ]]; do CLI_ALL_PATHS[$k]="/nonexistent/$k"; k=$((k + 1)); done
+            CLI_DETECT_DONE=""; detect_all_clis
+            offer_ai_cli_install >/dev/null 2>&1
+            echo "bash $BASH_VERSION: skipping the AI CLI install menu continues"
+          '
+          # Issue #382: the dsh identity probe builds an OPTIONAL `timeout` prefix as an
+          # array, and on stock macOS there is no `timeout`, so the array is empty and the
+          # expansion aborts the whole installer under `set -u`. The step above cannot
+          # reach that branch: this image HAS `timeout`, and with no `dsh` on PATH the
+          # probe is never called at all. So hide `timeout` and call it directly.
+          docker run --rm -v "$PWD":/w -w /w -e CODEMAN_INSTALL_SH_LIB=1 bash:3.2 bash -c '
+            set -euo pipefail
+            . /w/install.sh
+            printf "#!/bin/sh\necho \"DeepSeek Harness 0.1\"\n" > /tmp/dsh
+            printf "#!/bin/sh\necho \"dancer shell (Debian dsh)\"\n" > /tmp/not-dsh
+            chmod 755 /tmp/dsh /tmp/not-dsh
+            # A PATH the probe can still work on, minus the binary under test.
+            mkdir -p /tmp/nobin
+            for b in grep sh; do ln -sf "$(command -v $b)" "/tmp/nobin/$b"; done
+            export PATH=/tmp/nobin
+            if command -v timeout >/dev/null 2>&1; then
+              echo "timeout is still on PATH, so this is NOT exercising the empty-array branch" >&2
+              exit 1
+            fi
+            dsh_banner_probe /tmp/dsh
+            if dsh_banner_probe /tmp/not-dsh; then
+              echo "identity probe accepted a foreign dsh" >&2
+              exit 1
+            fi
+            echo "bash $BASH_VERSION: dsh identity probe survives a missing timeout"
+          '
+          # Installer v2: the question phase runs before the build, and every decision it
+          # takes is bash logic over stubbed tailscale state. Drive the flags, the launch
+          # default, the occupied-:443 menu and the rename question with canned answers,
+          # so a bash-4 construct or a flipped default in any of them fails here, not on a
+          # Mac. The JSON parsers need node (absent in this image) and are stubbed; their
+          # own coverage is test/install-sh-invariants.test.ts plus the vitest gate.
+          docker run --rm -v "$PWD":/w -w /w -e CODEMAN_INSTALL_SH_LIB=1 -e HOME=/tmp/h bash:3.2 bash -c '
+            set -euo pipefail
+            mkdir -p /tmp/h
+            . /w/install.sh
+            parse_flags --tailscale --service --name Build-Box --port 4000
+            [[ "$CODEMAN_TAILSCALE" == "1" && "$LAUNCH_PRESET" == "2" && "$TS_NAME" == "Build-Box" && "$CODEMAN_PORT" == "4000" ]]
+            [[ "$(ts_sanitize_name "$TS_NAME")" == "build-box" ]]
+            has_tty() { return 0; }
+            ANSWER=""; read_reply() { eval "$1=\"\$ANSWER\""; }
+            systemctl() { return 0; }
+            LAUNCH_PRESET=""; NONINTERACTIVE=0
+            choose_launch_mode linux >/dev/null 2>&1
+            [[ "$LAUNCH_CHOICE" == "2" ]]
+            check_tailscale() { return 0; }
+            ts_status_field() { case "$1" in "s.BackendState") printf Running ;; "s.Self && s.Self.DNSName") printf "box.tail.ts.net." ;; esac; }
+            ts_backend_state() { printf Running; }
+            ts_dns_name() { printf box.tail.ts.net; }
+            ts_serve_443_target_port() { printf 8080; }
+            ts_serve_find_port_mapping() { :; }
+            ts_serve_port_used() { return 1; }
+            detect_tailscale_serve_url() { :; }
+            tailscale_choose_mapping >/dev/null 2>&1
+            [[ "$TS_SERVE_MODE" == "path" && "$BIND_BASE_URL" == "/codeman" ]]
+            RENAMED=""; tailscale_rename_node() { RENAMED="$1"; }
+            TS_NAME=""; tailscale_choose_name >/dev/null 2>&1
+            [[ -z "$RENAMED" ]]
+            # A flag re-run keeps the password the unit already carries (and so
+            # never writes the unauthenticated ack), and the hand-start line the
+            # done screen prints carries every non-default value.
+            read_existing_binding() { EXISTING_FOUND=1; EXISTING_HOST=0.0.0.0; EXISTING_PASSWORD=s3cret; EXISTING_ACK=0; EXISTING_BASE_URL=""; }
+            CODEMAN_HOST=0.0.0.0; CODEMAN_TAILSCALE=0; unset CODEMAN_PASSWORD; BIND_ACK=0
+            choose_network_binding >/dev/null 2>&1
+            [[ "$BIND_PASSWORD" == "s3cret" && "$BIND_ACK" == "0" ]]
+            BIND_HOST=0.0.0.0; BIND_PASSWORD=x; BIND_ACK=0; BIND_BASE_URL=/codeman; CODEMAN_PORT=4000
+            [[ "$(start_command_hint)" == "CODEMAN_HOST=0.0.0.0 CODEMAN_PASSWORD="*" CODEMAN_BASE_URL=/codeman CODEMAN_PORT=4000 codeman web" ]]
+            RECONFIGURE=0; parse_flags --port 4001; [[ "$RECONFIGURE" == "1" ]]
+            echo "bash $BASH_VERSION: question phase (flags, launch default, occupied :443, rename opt-in, kept password, start line) ok"
+          '
+
+      - name: CLI catalogue artifacts are in sync with stock.ts
+        run: npm run generate:cli-catalog -- --check
+
       - name: Server boot smoke test
         run: |
           set -u
@@ -87,10 +205,25 @@ jobs:
           fi
 
       - name: Run unit & integration tests
-        # Excludes the browser-driven mobile suite (test/mobile/**); see config/vitest.ci.config.ts.
+        # Excludes the suites that need chromium, per-machine PNG baselines or a
+        # quiet machine — see config/test-suites.ts for the list and the reason
+        # behind each entry. Identical to what `npm test` runs locally.
         # Safe in CI: TmuxManager no-ops all shell commands under VITEST (test/setup.ts).
         run: npm run test:ci
 
-# Note: The browser-driven mobile suite (test/mobile/**) is excluded from CI —
-# it needs a live server + chromium + environment-specific PNG baselines.
-# Run it locally/manually. All other tests run via the `test` job above.
+      - name: Run xterm-zerolag-input package tests
+        # Layers 1-3 of the predictive-echo suites (unit laws, fixture replay,
+        # seeded fuzz): deterministic, no browser, no live server. Depends on
+        # the ROOT `npm ci` above — workspaces hoist the package's vitest into
+        # the root node_modules; do not add a separate install here.
+        run: npx vitest run
+        working-directory: packages/xterm-zerolag-input
+
+# Note: three suites are excluded from CI, each with its own local runner:
+#   npm run test:browser  Playwright + chromium (+ a live server, and a real
+#                         codex binary for codex-predictive-echo)
+#   npm run test:mobile   the above plus environment-specific PNG baselines
+#   npm run test:perf     wall-clock benchmarks; need an otherwise idle machine
+# config/test-suites.ts holds the globs; the configs derive from it so the
+# exclusions here and those runners cannot drift apart. Everything else runs in
+# the `test` job above, which is the same thing `npm test` runs.

.github/workflows/wiki-sync.yml

@@ -0,0 +1,109 @@
+name: Sync Wiki
+
+# Publishes docs/wiki/ to the repository's GitHub wiki.
+#
+# The wiki is a separate git repo with no CI and no review, so the source of truth
+# lives in docs/wiki/ and this workflow mirrors it. Browser edits to the wiki are
+# overwritten by the next sync; fix pages with a PR against docs/wiki/ instead.
+#
+# One-time setup: GitHub only creates <repo>.wiki.git once the first page has been
+# saved in the browser. Save a stub page at /wiki/_new before the first run.
+#
+# Token: GITHUB_TOKEN can push to the wiki on most repos but not all. If a run fails
+# with 403, add a fine-grained PAT with wiki write access as the WIKI_TOKEN secret;
+# it is preferred automatically when present. Note the 403 usually surfaces on the
+# PUSH, not the clone: this repo is public, so a read-only token still clones the
+# wiki fine. Both steps carry the hint.
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'docs/wiki/**'
+      - '.github/workflows/wiki-sync.yml'
+  workflow_dispatch:
+
+concurrency: ${{ github.workflow }}
+
+jobs:
+  sync:
+    name: Push docs/wiki to the wiki
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v6
+
+      - name: Clone wiki
+        env:
+          WIKI_TOKEN: ${{ secrets.WIKI_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          if ! git clone "https://x-access-token:${WIKI_TOKEN}@github.com/${GITHUB_REPOSITORY}.wiki.git" wiki 2>"${RUNNER_TEMP}/clone-err.txt"; then
+            cat "${RUNNER_TEMP}/clone-err.txt"
+            echo "::error::Could not clone ${GITHUB_REPOSITORY}.wiki.git. If this says 'Repository not found', the wiki has never had a page: save one at https://github.com/${GITHUB_REPOSITORY}/wiki/_new and re-run. If it says 403, add a WIKI_TOKEN secret."
+            exit 1
+          fi
+
+      - name: Mirror pages
+        run: |
+          set -euo pipefail
+
+          # The mirror deletes before it copies, so an empty source would wipe
+          # every published page and the commit step would happily push that. A
+          # MISSING directory already fails safely (cp aborts under set -e); an
+          # empty one does not, so check explicitly. This is the one failure mode
+          # here that destroys something a browser edit cannot get back.
+          if [ ! -d docs/wiki ]; then
+            echo "::error::docs/wiki does not exist. Refusing to mirror, which would delete the entire published wiki."
+            exit 1
+          fi
+          pages=$(find docs/wiki -maxdepth 1 -name '*.md' | wc -l)
+          if [ "$pages" -eq 0 ]; then
+            echo "::error::docs/wiki contains no .md pages. Refusing to mirror, which would delete the entire published wiki."
+            exit 1
+          fi
+          echo "Mirroring ${pages} pages."
+
+          find wiki -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +
+          cp -R docs/wiki/. wiki/
+
+      - name: Stamp the documented version
+        run: |
+          set -euo pipefail
+          # _Footer.md renders on every page and used to carry a hand-written
+          # version, which went stale on every release because nothing refreshed
+          # it. It carries {{VERSION}} instead and the series is stamped here.
+          series="$(node -p "require('./package.json').version.split('.').slice(0,2).join('.') + '.x'")"
+          # grep exits 1 when it matches nothing, which under `set -o pipefail`
+          # would fail the step instead of warning, so test before substituting.
+          if grep -rlq '{{VERSION}}' wiki/; then
+            grep -rlZ '{{VERSION}}' wiki/ | xargs -0 -r sed -i "s/{{VERSION}}/${series}/g"
+          else
+            echo "::warning::No {{VERSION}} placeholder found in docs/wiki. The published version line can no longer be refreshed automatically."
+          fi
+          if grep -rq '{{VERSION}}' wiki/; then
+            echo "::error::A {{VERSION}} placeholder survived substitution and would be published verbatim."
+            exit 1
+          fi
+          echo "Stamped version ${series}."
+
+      - name: Commit and push
+        run: |
+          set -euo pipefail
+          cd wiki
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git add -A
+          if git diff --quiet --cached; then
+            echo "Wiki already up to date."
+            exit 0
+          fi
+          git commit -m "docs: sync wiki from docs/wiki @ ${GITHUB_SHA:0:7}"
+          if ! git push 2>"${RUNNER_TEMP}/push-err.txt"; then
+            cat "${RUNNER_TEMP}/push-err.txt"
+            echo "::error::Could not push to ${GITHUB_REPOSITORY}.wiki.git. A 403 here means the token can read the wiki but not write it, which is the usual GITHUB_TOKEN case: add a fine-grained PAT with wiki write access as the WIKI_TOKEN secret."
+            exit 1
+          fi

.gitignore

@@ -2,6 +2,9 @@
 .agents/
 skills-lock.json
 
+
+# In-session decision scratchpad (context-survival mechanism, not a deliverable)
+DECISIONS.md
 # Written by install.sh into end-user clones when setup finishes
 .install-complete
 
@@ -45,6 +48,10 @@ Thumbs.db
 .env.local
 .env.*.local
 
+# Local Compose customisation (host-specific, not part of the project)
+docker-compose.override.yml
+docker-compose.override.yaml
+
 # State files (local to each machine)
 .claude/ralph-loop.local.md
 
@@ -93,8 +100,6 @@ packages/gesture-control/.vite/
 # Claude Code plan tracking
 plan.json
 
-# Unfinished TUI (local development only)
-src/tui/
 .claude/
 media-assets/
 commands
@@ -104,3 +109,7 @@ readme-preview.mjs
 
 # Uploaded images land here under each session working dir (runtime artifact)
 .claude-images/
+
+# Local-LLM harness smoke-test config (real IPs/keys) — see the .example.json
+# alongside it in scripts/, which IS tracked as the template.
+scripts/local-llm-test.config.json

AGENTS.md

@@ -2,7 +2,8 @@
 
 Canonical agent/contributor guidance for this repository lives in [CLAUDE.md](CLAUDE.md) —
 project structure, build/test/lint commands, code style, testing safety rules
-(never run the full suite inside a managed tmux session), security notes, and
+(`npm test` is the CI gate and is safe to run bare; the three excluded suites
+have their own runners), security notes, and
 the deployment workflow are all maintained there. Please read it before making
 changes, and keep it the single source of truth rather than duplicating
 sections here.
@@ -10,7 +11,7 @@ sections here.
 Quick pointers:
 
 - Type check: `tsc --noEmit` · Lint: `npm run lint` · Format: `npm run format:check`
-- Targeted tests only: `npm test -- test/<file>.test.ts` (bare `npm test` is unsafe in managed sessions)
+- Tests: `npm test` (the CI gate, safe to run bare) or `npm test -- test/<file>.test.ts` for one file
 - Route tests use `app.inject()`; new tests needing ports must pick a unique `const PORT =`
 - Branch off `master` for all work; Conventional Commit-style messages (`fix(mobile): ...`)
 - Never commit secrets or local state from `~/.codeman/`

CLAUDE.md

@@ -2,21 +2,21 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-> Deep implementation detail lives in [`docs/architecture-invariants.md`](docs/architecture-invariants.md). This file holds the rules that prevent mistakes; that file holds the mechanisms, file inventories, and the history behind each rule. Pointers below are written as `→ architecture-invariants#anchor`. When the goal is raw throughput, [`docs/SPEEDRUN.md`](docs/SPEEDRUN.md) is the fast-execution protocol (it removes ceremony, never the safety rules here).
+> Deep implementation detail lives in [`docs/architecture-invariants.md`](docs/architecture-invariants.md). This file holds the rules that prevent mistakes; that file holds the mechanisms, file inventories, and the history behind each rule. Pointers below are written as `→ architecture-invariants#anchor`. When the goal is raw throughput, [`docs/SPEEDRUN.md`](docs/SPEEDRUN.md) is the fast-execution protocol (it removes ceremony, never the safety rules here). The user-facing manual is `docs/wiki/` (mirrored to the GitHub wiki by CI; see the CI note under Additional Commands), and `AGENTS.md` deliberately just points here.
 >
 > **This file is in `.prettierignore` on purpose.** Prettier's markdown printer escapes underscores inside the glob-heavy paths used throughout (`agent-*.jsonl` became `agent-\_.jsonl`, collapsing backtick spans and corrupting a whole paragraph). Do not remove the ignore entry, and do not run `prettier --write` on it.
 >
-> **Repo root is kept short on purpose** (the README sits below the file listing on GitHub). Config lives in `config/` (`eslint.config.js`, `knip.json`, the vitest configs), Prettier's config is the `"prettier"` key in `package.json`, and `SECURITY.md` is under `.github/`. Root-only files are the ones tools genuinely require there: `CLAUDE.md` + `AGENTS.md` (loaded from the root by Claude Code / Codex), `CHANGELOG.md` (changesets writes it next to `package.json`), `tsconfig.json`, `.editorconfig`, `.nvmrc`/`.npmrc`, `.prettierignore` (resolved relative to cwd), `LICENSE` (GitHub detection) and `install.sh` (its raw URL is the published install one-liner). Don't relocate those.
+> **Repo root is kept short on purpose** (the README sits below the file listing on GitHub). Config lives in `config/` (`eslint.config.js`, `knip.json`, the vitest configs), Prettier's config is the `"prettier"` key in `package.json`, and `SECURITY.md` is under `.github/`. Root-only files are the ones tools genuinely require there: `CLAUDE.md` + `AGENTS.md` (loaded from the root by Claude Code / Codex), `CHANGELOG.md` (changesets writes it next to `package.json`), `tsconfig.json`, `.editorconfig`, `.nvmrc`/`.npmrc`, `.prettierignore` (resolved relative to cwd), `LICENSE` (GitHub detection), `.dockerignore` (the build context is the repo root, so Docker resolves it there and nowhere else) and `install.sh` (its raw URL is the published install one-liner). `.claude-plugin/marketplace.json` is root-only for the same reason: `/plugin marketplace add Ark0N/Codeman` reads it from the repo root and nowhere else, which makes the repo its own plugin marketplace. The one plugin it lists is `plugins/codeman/` (manifest + README + a MIRROR of `skills/codeman/`), and ⚠️ the plugin is a small separate directory on purpose: `claude plugin install` copies the plugin root into its cache, and a plugin root that carries a `package.json` gets an **npm install** at install time (measured with the repo root as plugin root: 832 MB, 511 packages and this repo's postinstall on every installer's machine), while a symlink to `skills/codeman` would dangle in the copy. `skills/codeman/` stays the single source; `scripts/sync-plugin.mjs` mirrors it and writes `package.json`'s version into both manifests inside `version-packages`, and `test/plugin-manifest.test.ts` pins the byte-identity, the versions, the absence of a `package.json` in the plugin root and that no other component (`commands/`, `agents/`, `hooks/`, `.mcp.json`, `settings.json`) rides along. `npm run check:plugin` runs that drift check plus both strict validations with EXPLICIT paths (`plugins/codeman`, `.claude-plugin/marketplace.json`): a bare `.` argument copied out of prose reads as a full stop and gets dropped, which surfaces as `missing required argument 'path'`. Needs the `claude` CLI, so it is a local check, not a CI step. Don't relocate those.
 
 ## Quick Reference
 
 | Task        | Command                                                                                                                                                             |
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Dev server  | `npm run dev` (or `npx tsx src/index.ts web`)                                                                                                                       |
-| Type check  | `tsc --noEmit`                                                                                                                                                      |
+| Type check  | `npm run typecheck` (= `tsc --noEmit`)                                                                                                                                                      |
 | Lint        | `npm run lint` (fix: `npm run lint:fix`)                                                                                                                            |
 | Format      | `npm run format` (check: `npm run format:check`)                                                                                                                    |
-| Single test | `npm test -- test/<file>.test.ts` (or `npx vitest run --config config/vitest.config.ts test/<file>.test.ts`) — ⚠ **never** run bare `npm test`, see Testing section |
+| Tests       | `npm test` (the CI gate — safe to run bare) · one file: `npm test -- test/<file>.test.ts` · see Testing for the excluded suites |
 | Build       | `npm run build` (esbuild via `scripts/build.mjs`, NOT tsc — `tsc --noEmit` is type-check only)                                                                      |
 | Production  | `npm run build && systemctl --user restart codeman-web`                                                                                                             |
 
@@ -34,6 +34,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - To land a commit on master **without** switching branches (which would yank the tree out from under the other session): `git push origin HEAD:master` then `git branch -f master HEAD`. Never `git checkout master` to "fix" it.
 - **Never `git add -A`/`git add .`** — stage explicit paths. A sweep will pick up another session's WIP.
 - Another session's broken WIP can block `npm run build`, since `tsc` is the first step and the build gates on it. That is not your bug to fix. ⚠️ `tsc` still EMITS on type errors, so a failed `npm run build` leaves a rebuilt `dist/index.js` compiled from their tree; check what it pulled in before restarting the service. To deploy frontend-only changes past a blocked `tsc`, run the asset stage of `scripts/build.mjs` (everything after the `tsc`/`chmod` lines is independent of it).
+- **A pre-push failure in a file you did not touch is another session's WIP.** Push with `CODEMAN_SKIP_PREPUSH=1 git push` and leave it alone. (The hook already skips itself when the tree has uncommitted changes in a path it checks, so this mostly happens once the other session has committed.)
 
 ## CRITICAL: Always Test Before Deploying
 
@@ -43,11 +44,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 2. **Frontend changes**: Use Playwright to load the page and assert the UI renders correctly. Use `waitUntil: 'domcontentloaded'` (not `networkidle` — SSE keeps the connection open). Wait 3-4s for polling/async data to populate, then check element visibility, text content, and CSS values
 3. **Only after verification passes**, proceed with COM
 
-The production server caches static files for 1 year, `immutable` (`maxAge: '1y'` in `server.ts`). To avoid stale frontend after a deploy, `renderIndexHtml` runs `cacheBustAssets(html)` — it appends `?v=<mtime>` to **every same-origin `.js`/`.css`** reference (mtime memoized ~1s so a burst of renders is cheap; external/already-versioned/missing refs untouched). Because `index.html` is served `no-cache`, a **normal reload now picks up edited modules/styles — no hard refresh needed** (the gesture bundle is injected separately with its own `?v=`). If you add an asset referenced by an _absolute_ URL or from JS rather than a `<script>/<link>` tag, it won't be auto-busted.
+The production server caches static files for 1 year, `immutable` (`maxAge: '1y'` in `server.ts`). To avoid stale frontend after a deploy, `renderIndexHtml` runs `cacheBustAssets(html)` — it appends `?v=<mtime>` to **every same-origin `.js`/`.css`** reference (mtime memoized ~1s so a burst of renders is cheap; external/already-versioned/missing refs untouched). Because `index.html` is served `no-cache`, a **normal reload now picks up edited modules/styles — no hard refresh needed** (the gesture bundle is injected separately with its own `?v=`). If you add an asset referenced by an _absolute_ URL or from JS rather than a `<script>/<link>` tag, it won't be auto-busted. ⚠️ **`index.html` itself is the exception: it is read ONCE into `indexHtmlTemplate` in the `WebServer` constructor**, so editing markup in dev needs a server restart (edited `.js`/`.css` do not) — otherwise you debug a "CSS class that doesn't apply" that is really an element still missing from the served HTML.
 
 ## COM Shorthand (Deployment)
 
-Uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) via `@changesets/cli`. What SemVer actually covers (the CLI + documented env vars are public; the HTTP/SSE API, on-disk state, and experimental features are internal/unstable) is defined in `docs/versioning-policy.md`. Security reporting + known limitations live in `.github/SECURITY.md`.
+Uses [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`) via `@changesets/cli`. What SemVer actually covers (the CLI, documented env vars, **and the HTTP/SSE API under `/api/v1`**: endpoint paths, response envelope, `errorCode` values and SSE event names are public/stable; on-disk state, internal TS modules, and experimental features are internal/unstable) is defined in `docs/versioning-policy.md`. Third-party integration surfaces are documented in `docs/extending-codeman.md`. Security reporting + known limitations live in `.github/SECURITY.md`.
 
 When user says "COM":
 
@@ -70,23 +71,26 @@ When user says "COM":
 4. **Sync CLAUDE.md version**: Update the `**Version**` line below to match the new version from `package.json`
 5. **Commit and deploy**: verify the branch first (`git branch --show-current`), then stage EXPLICIT paths — never `git add -A`, which has swept another session's WIP into a release. `git status --short` and account for every line before committing:
    `git add <paths> && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`
-6. **Wait for CI**: after `git push`, TWO workflows fire per master push — `CI` and `Release` (the npm publish + GitHub release). List both runs for the pushed commit with `gh run list --commit $(git rev-parse HEAD) --json databaseId,workflowName` and watch EACH with `gh run watch <id> --exit-status`. Confirm both pass before considering the release done (`gh run list -L 1` returns only one of the two).
+6. **Refresh the getcodeman.com version badge**: the landing page's status bar carries the release version (`v<x.y.z> · getcodeman.com · MIT`), so it goes stale on every release if nobody bumps it. The site source and its deploy script are maintained outside this repository, on the maintainer's machine only; follow the local site handbook there, which also covers the numbers strip and `sitemap.xml` refresh that belong in the same pass. Poll production (`curl -s https://getcodeman.com/ | grep v<x.y.z>`) before calling it done, since the edge lags a deploy by up to a minute. Not applicable to contributor clones — skip it and say so.
+7. **Wait for CI**: after `git push`, TWO workflows fire per master push — `CI` and `Release` (the npm publish + GitHub release). List both runs for the pushed commit with `gh run list --commit $(git rev-parse HEAD) --json databaseId,workflowName` and watch EACH with `gh run watch <id> --exit-status`. Confirm both pass before considering the release done (`gh run list -L 1` returns only one of the two).
+
+8. **Announce it in Discussions**: every release gets a post in the [Announcements](https://github.com/Ark0N/Codeman/discussions/categories/announcements) category, shaped like #418 and #302: the short version first (one bold lead-in per theme, features before fixes, what it does for the user rather than how it works), contributor @-mentions inline where their work is described (a mention notifies them, and a contributor reposting is the cheapest reach this project has), a link to the release, and the Thanks names at the end. Casual first-person voice, no em-dashes, humanizer pass when the skill is available. A same-day follow-on patch (1.28.1 after 1.28.0) is folded into the previous post as an edit, never a second thread. Post it with `gh api graphql -F body=@<file> -f title='Codeman <x.y.z>: <hook>' -f repo=R_kgDOQ-SMDg -f cat=DIC_kwDOQ-SMDs4DCHZE -f query='mutation($repo:ID!,$cat:ID!,$title:String!,$body:String!){createDiscussion(input:{repositoryId:$repo,categoryId:$cat,title:$title,body:$body}){discussion{number url}}}'` (the repo's node id and its Announcements category id; `pinDiscussion` does not exist in the API, so pinning stays a click in the UI). This step exists because announcements stopped at 1.18 (#302) while ten releases shipped with nobody notified; #418 is the backfill covering 1.19.0 to 1.28.1, and release notes only count as content once they reach a surface people are subscribed to.
 
 CI runs `npm run check:lockfile` on every push/PR, so lockfile drift fails the build even if the `version-packages` script is bypassed.
 
-**Version**: 1.9.9 (must match `package.json`)
+**Version**: 1.33.2 (must match `package.json`)
 
 ## Project Overview
 
 Codeman is a Claude Code session manager with web interface and autonomous Ralph Loop. Spawns Claude CLI via PTY, streams via SSE, supports respawn cycling for 24+ hour autonomous runs.
 
-**Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, node-pty, xterm.js. Supports Claude Code, OpenCode, Codex (OpenAI), Gemini (Google, enterprise-only since Google's June 2026 consumer cutover), and Antigravity (`agy`, Google) CLIs via pluggable CLI resolvers (`SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity'`).
+**Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, node-pty, xterm.js. Supports Claude Code, OpenCode, Codex (OpenAI), Gemini (Google, enterprise-only since Google's June 2026 consumer cutover), Antigravity (`agy`, Google), Pi (pi.dev), Grok Build (`grok`, xAI), DeepSeek Harness (`dsh`) and OMP (`omp`) CLIs via pluggable CLI resolvers (`SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi' | 'grok' | 'deepseek' | 'omp'`).
 
 **TypeScript Strictness** (see `tsconfig.json`): `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `allowUnreachableCode: false`, `allowUnusedLabels: false`.
 
 **Requirements**: Node.js 22+, Claude CLI, tmux
 
-**Git**: Main branch is `master`. SSH session chooser: `sc` (interactive), `sc 2` (quick attach), `sc -l` (list).
+**Git**: Main branch is `master`. Terminal session dashboard: `codeman tui` (`--list` to list, `codeman tui <n>` to attach).
 
 ## Additional Commands
 
@@ -94,43 +98,53 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 | Task                           | Command                                                                                                                                                                                                        |
 | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Terminal dashboard             | `codeman tui` (`--list` prints the numbered list and exits, `codeman tui <n>` attaches to row n; both short-circuit before any screen setup). Needs a TTY; without a server it starts attach-only. `docs/tui.md` |
 | Dev with TLS                   | `npx tsx src/index.ts web --https`                                                                                                                                                                             |
 | Override window title hostname | `npx tsx src/index.ts web --title-hostname <name>` (default: `os.hostname()` — `codeman:<name>` is used for tab title, title-flash, and OS desktop notification prefix)                                        |
 | Bind a non-loopback host       | `npx tsx src/index.ts web --host 0.0.0.0` (or `-H`; env `CODEMAN_HOST`; default `127.0.0.1`). Without `CODEMAN_PASSWORD` it **starts but warns loudly** — see Common Gotchas + `docs/security-architecture.md` |
+| Mount under a reverse-proxy sub-path | `npx tsx src/index.ts web --base-url /codeman` (env `CODEMAN_BASE_URL`; default `/`). Normalized in `src/config/base-path.ts` (`''` = root). See Reverse-proxy base path below + `docs/wiki/Remote-Access.md` |
 | Continuous typecheck           | `tsc --noEmit --watch`                                                                                                                                                                                         |
-| Watch-mode test                | `npm run test:watch -- test/<file>.test.ts` (always pass a file — bare watch includes the browser suites)                                                                                                      |
+| Watch-mode test                | `npm run test:watch -- test/<file>.test.ts` (runs the CI gate's config; pass a file to narrow it)                                                                                                               |
 | Test coverage                  | `npm run test:coverage`                                                                                                                                                                                        |
 | Dead-code sweep                | `npm run knip` (config in `config/knip.json`, passed via `--config`)                                                                                                                                          |
 | Rebuild gesture overlay        | `npm run build:gesture` (esbuild `packages/gesture-control/src/codeman/entry.ts` → `src/web/public/gesture/gesture-codeman.js`; commit the result)                                                             |
-| Build the docker agent image   | `node scripts/build-agent-image.mjs` (builds `codeman/agent:base` from `docker/agent.Dockerfile`; prerequisite for Docker cases; `--engine`/`--image`/`--no-cache`)                                            |
+| Regenerate the CLI catalogue   | `npm run generate:cli-catalog` (`--check` to fail on drift). Rewrites `config/clis.stock.json` **and** the marked block in `install.sh` from `stock.ts`. ⚠ **Commit both.** They are what `install.sh` and the Docker agent image read, since neither can import TypeScript; `test/cli-catalog-sync.test.ts` and a CI `--check` step fail if either goes stale. See `docs/cli-registry.md` |
+| Build the docker agent image   | `node scripts/build-agent-image.mjs --no-cache` (builds `codeman/agent:base` from `docker/agent.Dockerfile`; prerequisite for Docker cases; `--engine`/`--image`). ⚠ **Always `--no-cache`** — a plain rebuild re-uses the cached `npm install -g` layer and silently keeps the CLIs frozen at their original versions, which once shipped a BROKEN codex while reporting success. See `docs/docker-cases.md` |
 | Gesture playground             | `npm run dev` **in** `packages/gesture-control/` (standalone vite demo, fake tabs)                                                                                                                             |
 | Check public-asset formatting  | `npm run check:public-assets` (prettier-checks `src/web/public/**` text assets; `scripts/check-public-assets.mjs`)                                                                                             |
 | Frontend JS syntax check       | `npm run check:frontend-syntax` (`scripts/check-frontend-syntax.mjs`; runs in CI)                                                                                                                              |
-| CI-equivalent test sweep       | `npm run test:ci` (full suite minus browser/perf — see Testing)                                                                                                                                                |
+| Browser-test exclusion check   | `npm run check:browser-excludes` (`scripts/check-browser-test-excludes.mjs`; runs in CI, <1s). Fails if a test importing playwright/puppeteer is still collected by `config/vitest.ci.config.ts`; add it to `BROWSER_TEST_GLOBS` in `config/test-suites.ts` |
+| Pre-push hook                  | Installed by `npm install` (`scripts/git-hooks.mjs`, via postinstall): runs the static CI checks (~10-40s) before `git push`. Skip once: `CODEMAN_SKIP_PREPUSH=1 git push`. Skips itself with a notice when HEAD is not the pushed commit or the tree has uncommitted changes the checks would read. Marker-owned, so a hand-written `pre-push` is never overwritten; installs ONLY into the repo's own `<git-common-dir>/hooks` (worktree-safe; a `core.hooksPath` elsewhere, e.g. a global one, is left alone) |
+| Excluded-suite runners         | `npm run test:browser` · `npm run test:mobile` · `npm run test:perf` · `npm run test:all` (everything, environmental failures included) — see Testing                                                           |
 | Production start               | `npm run start`                                                                                                                                                                                                |
 | Production logs                | `journalctl --user -u codeman-web -f`                                                                                                                                                                          |
+| Detached server                | `codeman web -d` (`--status`, `--stop`; pidfile+log at `dataPath('web.pid'/'web.log')`). ⚠ Refuses to start a 2nd server on one data dir — see Instance isolation                                              |
+| Install/remove the service     | `codeman service install` / `status` / `uninstall` (systemd user unit on Linux, LaunchAgent on macOS; names from `config/service-names.ts`)                                                                     |
+| Dependency doctor              | `codeman doctor` (alias `check-deps`; `--json`, `--category core\|office\|other`). Probes Node/Claude CLI/tmux/LibreOffice/MS Office against `config/dependency-registry.ts`; engine is pure given an injectable `ProbeHost` |
+| Multi-user accounts            | `codeman users add <name>` / `passwd <name>` / `list` / `rm <name>` (writes `~/.codeman/users.json`, mode 0600; see Multi-user mode)                                                                            |
 
-**CI**: `.github/workflows/ci.yml` (push to master/main + PRs, Node 22) runs two jobs: **(1)** `check:lockfile`, `typecheck`, `lint`, `check:frontend-syntax`, `format:check`, then a **server boot smoke test** (`tsx src/index.ts web --port 3151` must answer `/api/status` within 30s); **(2)** the **unit/integration test suite** via `npm run test:ci` (`config/vitest.ci.config.ts` — excludes the browser-driven `test/mobile/**` suite, `perf-*` benchmarks, and 3 Playwright tests). Tests are tmux-safe in CI: `TmuxManager` no-ops all shell commands under `VITEST` (see Testing).
+**CI**: `.github/workflows/ci.yml` (push to master/main + PRs, Node 22) runs two jobs: **(1)** `check:lockfile`, `typecheck`, `lint`, `check:frontend-syntax`, `check:browser-excludes`, `format:check`, then a **server boot smoke test** (`tsx src/index.ts web --port 3151` must answer `/api/status` within 30s); **(2)** the **unit/integration test suite** via `npm run test:ci` (`config/vitest.ci.config.ts` — excludes the browser-driven `test/mobile/**` suite, `perf-*` benchmarks, and 14 Playwright tests; globs live in `config/test-suites.ts`), followed by the **`packages/xterm-zerolag-input` package tests** (a bare `npx vitest run` in that directory; its vitest is hoisted by the root `npm ci`, so no separate install, and `npm test` at the root does NOT run them). `npm test` runs this same config, so local green == CI green. Tests are tmux-safe in CI: `TmuxManager` no-ops all shell commands under `VITEST` (see Testing). A third workflow, `wiki-sync.yml`, fires only on master pushes touching `docs/wiki/**` and mirrors that directory to the GitHub wiki (browser edits to the wiki are overwritten by the next sync, so fix pages via `docs/wiki/`).
 
 **Code style**: Prettier (`singleQuote: true`, `printWidth: 120`, `trailingComma: "es5"`) — config lives in the **`"prettier"` key of `package.json`**, not a `.prettierrc` (keeps the repo root short; editors read it natively). `.prettierignore` stays at the root because Prettier resolves it relative to cwd. ESLint flat config (`config/eslint.config.js`) allows `no-console`, warns on `@typescript-eslint/no-explicit-any`. Ignores: `app.js`, `scripts/**/*.mjs`, `src/web/public/vendor/**`, `scripts/remotion/**`.
 
-**Prettier scope is deliberately narrow.** `npm run format` globs only `src/**/*.ts` and `src/web/public/**`, and `.prettierignore` then exempts most of `src/web/public/*.js` (app.js, styles.css, index.html, and 14 hand-formatted modules) plus `CLAUDE.md`. Those files are hand-formatted by design; `npm run check:public-assets` and `check:frontend-syntax` are what guard them (NUL bytes + JS syntax), not Prettier. Do not "fix" a file by adding it back to Prettier's scope.
+**Prettier scope is deliberately narrow.** `npm run format` globs only `src/**/*.ts` and `src/web/public/**` (`lint` only `src/**/*.ts`), and `.prettierignore` then exempts most of `src/web/public/*.js` (app.js, styles.css, **mobile.css**, index.html, upload.html, and 15 hand-formatted modules) plus `CLAUDE.md`. Those files are hand-formatted by design; `npm run check:public-assets` and `check:frontend-syntax` are what guard them (NUL bytes + JS syntax), not Prettier. Do not "fix" a file by adding it back to Prettier's scope.
 
 ## Common Gotchas
 
-- **Single-line prompts only** — `writeViaMux()` sends text+Enter separately; multi-line breaks Ink
+- **Single-line prompts only** — `writeViaMux()` sends text+Enter separately; multi-line breaks Ink. ⚠️ **Input must END with `\r` or Enter is never sent**: `sendInput()` only issues `send-keys Enter` when the payload contains a carriage return, a `\r`-less `POST /api/sessions/:id/input` still succeeds (send-and-wait even reports `delivered:true`) while the text sits unsubmitted on the composer, and any `wait` burns its whole timeout on a turn that never started. Embedded newlines are stripped, not rejected, so `"echo A\necho B\r"` runs the joined `echo Aecho B`. ⚠️ **Claude Code 2.1.277+ ignores Enter for the first 30-50 s after the composer paints** while still taking the typed text (measured 2026-09-19: an Enter at 28 s stranded the prompt, one at 51 s submitted it), so text+`\r` sent at readiness sits unsent with `0 tokens` and a `wait` burns its timeout. So the SERVER verifies every programmatic write that carried a `\r`: `SubmitVerifier` (`session-submit-verifier.ts`, armed from `writeViaMux`) reads the pane on a 2 s to 60 s schedule and re-sends Enter only while the LAST composer line (the CLI's own `promptGlyph`) verifiably still holds the head of what was sent; an empty composer, other text, or no composer line at all (a shell, a direct-PTY session) ends it, and a newer write replaces the schedule. The skill's `sendwait` keeps its own copy of the loop (`_composer_text` in `skills/codeman/preamble.sh`) for servers that predate this. The `shift+tab` footer only means the composer painted, never that Enter is accepted. ⚠️ **A prompt must never be written into the pane as ONE burst**: Claude Code 2.1.283 takes a `<text>\r` burst of ~100+ chars as a paste, its `\r` lands as a NEWLINE and the prompt strands (a later raw `\r` does not recover it, a tmux `send-keys Enter` does). So `POST .../input` routes a plain prompt (`isPlainPromptInput()`, route-helpers.ts: printable text + exactly one trailing `\r`) through `writeViaMux` even without `useMux`, AWAITED so the browser's serialized POST fallback keeps frame order; raw frames and an explicit `useMux:false` keep the direct write
 - **ESM only** — Never `require()`, use `await import()`. `tsx` masks CJS/ESM issues in dev but production breaks
 - **Package ≠ product name** — npm: `aicodeman`, product: **Codeman**. Release renames tags accordingly. Both `aicodeman` and `codeman` bin aliases are installed (`package.json` `bin`)
 - **Global regex `lastIndex`** — Shared `g`-flag patterns in loops must reset `lastIndex = 0` first, or use the `execPattern()` helper in `utils/regex-patterns.ts` (resets automatically)
-- **`envOverrides` flow `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` / `ANTIGRAVITY_*` env vars** — Set via `POST /api/sessions { envOverrides }`, stored on `Session._envOverrides`, exported by `tmux-manager.buildEnvExports()` at spawn time, persisted in `SessionState.envOverrides`. **Do NOT** write these to `<case>/.claude/settings.local.json` — that's the old path and creates UI/disk drift. (`GOOGLE_*` is the deliberately-broad Vertex-AI namespace for Gemini — see Multi-CLI prefix discipline.)
+- **`envOverrides` flow `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` / `ANTIGRAVITY_*` / `PI_*` / `GROK_*` / `XAI_*` / `DSH_*` / `DEEPSEEK_*` env vars, plus exact-key `CLAUDE_CONFIG_DIR`** — Set via `POST /api/sessions { envOverrides }`, stored on `Session._envOverrides`, exported by `tmux-manager.buildEnvExports()` at spawn time, persisted in `SessionState.envOverrides`. **Do NOT** write these to `<case>/.claude/settings.local.json` — that's the old path and creates UI/disk drift. (`GOOGLE_*` is the deliberately-broad Vertex-AI namespace for Gemini — see Multi-CLI prefix discipline.) `CLAUDE_CONFIG_DIR` (#255, exact match via `ALLOWED_ENV_KEYS` in `schemas.ts`) points a session at a separate Claude account/config dir for per-client subscriptions; it persists to state.json (a path, not a secret; losing it on restart would silently switch accounts). ⚠️ A relocated config dir writes transcripts outside `~/.claude/projects`, so the response viewer, subagent windows, ultracode panel and Read My Mind capture go blind for that session unless the user symlinks `projects` back into the shared tree (`ln -s ~/.claude/projects <configDir>/projects`). ⚠️ It is also one of claude's `privilegedEnvKeys` (Custom Model Endpoint Profiles, since it can redirect a session's traffic same as any other injected var), so in multi-user mode setting it via `envOverrides` is admin-only, and a non-granted owner's already-persisted `CLAUDE_CONFIG_DIR` is stripped on reboot-restore — silently returning that session to the default Claude account rather than the one it was pointed at (see `session-env-clamp.ts`). → [architecture-invariants#per-session-env-overrides-exact-key-allowlist-and-claude_config_dir](docs/architecture-invariants.md#per-session-env-overrides-exact-key-allowlist-and-claude_config_dir)
 - **Effort is NOT an env var** — never carry effort as `CLAUDE_CODE_EFFORT_LEVEL`: the env var hard-locks effort and blocks in-session `/effort` switching (incl. ultracode). It flows as the dedicated `effort` payload field → `Session._effort` → `claude --effort <level>` for regular levels incl. `max` (the settings `effortLevel` key is `enum(["low","medium","high","xhigh"]).catch(undefined)` — `max` gets SILENTLY dropped there), or `claude --settings '{"ultracode":true}'` for ultracode (rejected by `--effort`). Both are soft defaults the user can override anytime. Legacy env-var entries are auto-migrated by the Session constructor and unset from tmux sessions in `applyEnvOverrides()`. See `buildEffortCliArgs()` in `session-cli-builder.ts`, tests in `test/effort-injection.test.ts`
 - **Model choice flows via `settings.local.json`, NOT `--model` or env** — the App Settings **Claude Model** picker (`claudeModel` in `settings.json`) is read by `session-ui.js` at session create (wins over the legacy 1M-Opus toggles `opusContext1m`/`opusContext1mEnabled`), sent as the `modelOverride` payload field, and `updateCaseModel()` (`hooks-config.ts`) writes/deletes the `model` key in `<case>/.claude/settings.local.json`. This is the intended exception to the envOverrides rule above: model legitimately lives in `settings.local.json` (a soft default — in-session `/model` still works); env vars do not
-- **Multi-CLI prefix discipline** — env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `GEMINI_*` vs `ANTIGRAVITY_*`) and the `ALLOWED_ENV_PREFIXES` allowlist in `schemas.ts` enforces this. Gemini additionally allowlists the **broad `GOOGLE_*`** namespace (intentional: Vertex AI auth needs `GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI`; it is the loosest allowlist entry, affecting only the user's own spawned CLI). When adding a setting, decide which CLI(s) it applies to and gate the env export accordingly. Never blanket-forward all prefixes. Resolver design pattern: `docs/opencode-integration.md`
+- **Multi-CLI prefix discipline** — env-var prefix is CLI-specific (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `GEMINI_*` vs `ANTIGRAVITY_*` vs `PI_*` vs `GROK_*` vs `DSH_*`) and the `ALLOWED_ENV_PREFIXES` allowlist in `schemas.ts` enforces this; non-prefix exceptions are exact keys in `ALLOWED_ENV_KEYS` (currently only `CLAUDE_CONFIG_DIR`), never a widened prefix. Gemini additionally allowlists the **broad `GOOGLE_*`** namespace (intentional: Vertex AI auth needs `GOOGLE_CLOUD_PROJECT`/`GOOGLE_APPLICATION_CREDENTIALS`/`GOOGLE_GENAI_USE_VERTEXAI`; it is the loosest allowlist entry, affecting only the user's own spawned CLI), and Grok allowlists **`XAI_*`** for the same vendor-namespace reason (`XAI_API_KEY` is grok's documented auth var). When adding a setting, decide which CLI(s) it applies to and gate the env export accordingly. Never blanket-forward all prefixes. ⚠️ Pi is the case that proves the rule: its ~34 provider keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `HF_TOKEN`, …) share NO prefix, and the allowlist is one GLOBAL list applied by a refine with no mode context, so admitting them for pi would widen it for every mode at once — they stay out, and pi users authenticate via `/login` or the server process's own env. ⚠️ DeepSeek repeats pi's lesson exactly: a dsh `settings.yaml` can nominate ANY env var as a provider credential (`apiKeyEnv`), so only the vendor namespaces `DSH_*` (launcher inputs incl. `DSH_PERMISSION_MODE`) and `DEEPSEEK_*` (`DEEPSEEK_API_KEY`/`DEEPSEEK_BASE_URL`) are admitted; foreign provider keys authenticate from dsh's own files or the server env. Resolver design pattern: `docs/opencode-integration.md`, `docs/pi-integration.md`, `docs/grok-integration.md`, `docs/deepseek-integration.md`
 - **Zod `.optional()` rejects `null`** — accepts `undefined` only. When the frontend builds a request body with `JSON.stringify`, an explicit `null` field is preserved on the wire and fails validation with `INVALID_INPUT`. Convert `null` → `undefined` before stringifying (e.g. `field: value ?? undefined`), or declare the schema `.nullish()`. This has caused real shipped bugs twice
-- **`xterm-zerolag-input` is single-source** — the local-echo overlay source lives ONLY in `packages/xterm-zerolag-input/src/`, and is bundled into the **gitignored** `src/web/public/vendor/xterm-zerolag-input.js` (dev, by `scripts/postinstall.js`) and `dist/.../vendor/` (prod, by `scripts/build.mjs`). `app.js` only **consumes** it via `new LocalEchoOverlay(terminal)`; there is no inline copy. So: change the package source, then rerun the bundle step (`npm install` for dev, `npm run build` for prod). **Never hand-edit `app.js` for overlay behavior, and never commit the gitignored vendor bundle.** Always test on mobile after touching it. → [architecture-invariants#xterm-zerolag-input-is-single-source](docs/architecture-invariants.md#xterm-zerolag-input-is-single-source), `docs/local-echo-overlay-plan.md`
+- **Local-echo overlay stays on screen**: the overlay lays its wrapped lines out DOWNWARD from the prompt row, and the text has not reached the PTY yet, so the CLI never learns the prompt is long and nothing scrolls to make room. With the keyboard up only a handful of rows are visible, so a long prompt used to run off the bottom and the user typed blind. The block now grows UPWARD once it would pass the last visible row (optional `totalRows` in `RenderParams`; the line divs are opaque, so they cover transcript above), and a prompt taller than the viewport keeps its TAIL. ⚠️ Separately, `_shrinkPaddingToFit()` (mobile-handlers.js) must never shrink `main`'s padding-bottom below the MEASURED height of the fixed bars: on phones the toolbar and accessory bar are `position: fixed`, so that padding is the only thing reserving room for them, and taking it pulled the terminal's bottom row behind them. Tests: `packages/xterm-zerolag-input/test/overlay-renderer.test.ts`, `test/mobile-keyboard-bottom-padding.test.ts`.
+- **`xterm-zerolag-input` is single-source** — BOTH echo addons live ONLY in `packages/xterm-zerolag-input/src/`, bundled into TWO **gitignored** vendor files: `vendor/xterm-zerolag-input.js` (buffer overlay, entry `zerolag-input-addon.ts`) and `vendor/xterm-predictive-echo.js` (codex write-through, entry `predictive-echo-addon.ts`) — dev by `scripts/postinstall.js`, prod by `scripts/build.mjs`. `app.js`/terminal-ui.js only **consume** them via `new LocalEchoOverlay(terminal)` / `new PredictiveEchoOverlay(terminal)`; there is no inline copy. So: change the package source, then rerun the bundle step (`npm install` for dev, `npm run build` for prod). **Never hand-edit `app.js` for overlay behavior, and never commit the gitignored vendor bundles.** Always test on mobile after touching it. → [architecture-invariants#xterm-zerolag-input-is-single-source](docs/architecture-invariants.md#xterm-zerolag-input-is-single-source), `docs/local-echo-overlay-plan.md`
 - **Default bind is loopback-only; non-loopback without a password starts but warns** — the server defaults to `--host 127.0.0.1`. Binding non-loopback (`--host`/`-H`/`CODEMAN_HOST`) without `CODEMAN_PASSWORD` starts anyway but prints a loud warning; `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` acknowledges it. ⚠️ The production systemd unit passes no `--host`, so prod binds **localhost only**: reach it via `tailscale serve`/tunnel to `127.0.0.1`. A loopback bind is reachable through a same-host tunnel but NOT by a browser hitting the box's LAN IP. `install.sh` is separate and prompts for the binding (defaulting to LAN + a password), and preserves the existing binding on re-runs. → [architecture-invariants#default-bind-and-the-non-loopback-warning-path](docs/architecture-invariants.md#default-bind-and-the-non-loopback-warning-path), `docs/security-architecture.md`
-- **Instance isolation / multi-instance attach danger** — the data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts`. ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions**, resizing and mutating them. `$HOME` isolation is NOT enough because tmux is system-global. To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes dir + socket together), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually; `scripts/run-beta.sh` does this for a beta alongside prod. **Any new `~/.codeman/...` path MUST go through `dataPath()`**, never `join(homedir(), '.codeman', …)`. → [architecture-invariants#instance-isolation-and-the-multi-instance-attach-danger](docs/architecture-invariants.md#instance-isolation-and-the-multi-instance-attach-danger)
-- **node-pty's macOS `spawn-helper` ships without `+x`** (issues #6, #204): `node-pty@1.1.0` publishes `prebuilds/darwin-<arch>/spawn-helper` as mode 0644, and macOS launches every PTY through it, so a stock macOS install fails every session start with `Error: posix_spawnp failed.` **Linux can never reproduce it**: `spawn-helper` is an `OS=="mac"` gyp target and node-pty ships no Linux prebuild, so node-gyp always emits an executable helper there. ⚠️ Look in **`prebuilds/<platform>-<arch>/`**, not just `build/Release/`, which does not exist on macOS. Repair is a chmod, never a mandatory rebuild (that would require Xcode CLI tools and deletes `prebuilds/` before compiling): `npm run fix:node-pty` chmods every helper then proves it by really opening a PTY. `spawnPtyWithHelperRepair()` (`utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts` and self-heals a broken install on the first failure. → [architecture-invariants#node-ptys-macos-spawn-helper-must-be-executable](docs/architecture-invariants.md#node-ptys-macos-spawn-helper-must-be-executable)
+- **Instance isolation / multi-instance attach danger** — the data dir (`~/.codeman`) and tmux socket (`tmux -L codeman`) are PROCESS-WIDE and shared by every Codeman on the machine, derived from `CODEMAN_INSTANCE` via `src/config/instance.ts`. ⚠️ A 2nd instance on the SAME socket **discovers and attaches PTYs to the first instance's live sessions**, resizing and mutating them. `$HOME` isolation is NOT enough because tmux is system-global. To run two instances, give each a distinct `CODEMAN_INSTANCE` (scopes dir + socket together), or set `CODEMAN_TMUX_SOCKET` + `CODEMAN_DATA_DIR` individually; `scripts/run-beta.sh` does this for a beta alongside prod. **Any new `~/.codeman/...` path MUST go through `dataPath()`**, never `join(homedir(), '.codeman', …)`, and **any new `tmux -L` caller through `resolveTmuxSocketName()`** (both in `config/instance.ts`): the TUI shells out to tmux from a second process, and a hardcoded `codeman` there would point a beta instance at prod's panes. → [architecture-invariants#instance-isolation-and-the-multi-instance-attach-danger](docs/architecture-invariants.md#instance-isolation-and-the-multi-instance-attach-danger)
+- **node-pty's macOS `spawn-helper` ships without `+x`** (issues #6, #204): `node-pty@1.1.0` publishes `prebuilds/darwin-<arch>/spawn-helper` as mode 0644, and macOS launches every PTY through it, so a stock macOS install fails every session start with `Error: posix_spawnp failed.` **Linux can never reproduce it**: `spawn-helper` is an `OS=="mac"` gyp target and node-pty ships no Linux prebuild, so node-gyp always emits an executable helper there. ⚠️ The flip side of that: since Linux has no prebuild, `npm install` **needs a C/C++ toolchain there** (`make`, `g++`, `python3`), so `install.sh` checks for and installs one alongside Node/tmux/git — a stock Ubuntu 24 server has none and died inside node-gyp with `not found: make`. Do not drop that step. ⚠️ Look in **`prebuilds/<platform>-<arch>/`**, not just `build/Release/`, which does not exist on macOS. Repair is a chmod, never a mandatory rebuild (that would require Xcode CLI tools and deletes `prebuilds/` before compiling): `npm run fix:node-pty` chmods every helper then proves it by really opening a PTY. `spawnPtyWithHelperRepair()` (`utils/node-pty-repair.ts`) wraps every `pty.spawn()` in `session.ts` and self-heals a broken install on the first failure. → [architecture-invariants#node-ptys-macos-spawn-helper-must-be-executable](docs/architecture-invariants.md#node-ptys-macos-spawn-helper-must-be-executable)
 - **Headless screenshots: `deviceScaleFactor` MUST be 1, and write unique filenames** — under DSF=2 xterm's WebGL renderer draws glyphs at ~2× nominal size while still *reporting* nominal cell dims, so only the pixels reveal it and only the terminal font looks wrong. And overwriting a fixed output path leaves OS image viewers showing the old render, which reads as "the fix didn't work"; `scripts/capture-real-overview.mjs` mints a timestamped filename per run. Seed the per-device `localStorage` keys (`codeman:skin`, `codeman-font-size`, `codeman-app-settings`) so the capture matches a real device. → [architecture-invariants#headless-screenshot-capture](docs/architecture-invariants.md#headless-screenshot-capture)
 
 **Import conventions**: Utils from `./utils`, types from `./types` (barrel), config from specific `./config/*` files.
@@ -141,9 +155,11 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 | Domain           | Key files                                                                                              | Notes                                                                                            |
 | ---------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| **Entry**        | `src/index.ts`, `src/cli.ts`                                                                           |                                                                                                  |
-| **Session**      | `src/session.ts` ★, `session-manager`, `session-auto-ops`, `session-cli-builder`, `session-task-cache`, `session-order` (pure), `session-pty-exit-breaker`, `usage-limit-patterns`, `usage-telemetry`; `src/services/unified-session-service.ts` | Pure/unit-tested helpers are split out of `session.ts` on purpose                                 |
-| **Mux**          | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` ★                                  |                                                                                                  |
+| **Entry**        | `src/index.ts`, `src/cli.ts`, `daemon-control`, `service-installer`, `config/service-names`, `cli-style` | The last three back `web -d` / `service install`; `cli-style` is the shared palette/table/spinner/confirm kit |
+| **TUI**          | `src/tui/`: `tui-app` ★ + `tui-client` (the only IO) over a pure core (`-model`, `-layout`, `-render`, `-keys`, `-ansi`, `-composer`, `-approvals`, `-digest`, `-sse`, `-types`) | `codeman tui`, a CLIENT of the server, never a second brain. Design doc: `docs/tui-plan.md`; user guide `docs/tui.md` |
+| **DeepSeek**     | `src/utils/deepseek-cli-resolver.ts`, `src/deepseek-status-shim.ts`, `src/deepseek-web-server.ts` (background `dsh web`, not a session) | `dsh` is a PROFILE LAUNCHER, not an agent; read `docs/deepseek-integration.md` first |
+| **Session**      | `src/session.ts` ★, `session-manager`, `session-auto-ops`, `session-cli-builder`, `session-task-cache`, `session-order` (pure), `session-pty-exit-breaker`, `session-trust-dialog` (pure), `usage-limit-patterns`, `usage-telemetry`; `src/services/unified-session-service.ts` | Pure/unit-tested helpers are split out of `session.ts` on purpose                                 |
+| **Mux**          | `src/mux-interface.ts`, `src/mux-factory.ts`, `src/tmux-manager.ts` ★, `src/proc-tree.ts` (pure, bounded descendant walk)                                  |                                                                                                  |
 | **Respawn**      | `src/respawn-controller.ts` ★ + 4 helpers (`-adaptive-timing`, `-health`, `-metrics`, `-patterns`)      | Read `docs/respawn-state-machine.md` first                                                       |
 | **Ralph**        | `src/ralph-tracker.ts` ★, `src/ralph-loop.ts` + 5 helpers (`-config`, `-fix-plan-watcher`, `-plan-tracker`, `-stall-detector`, `-status-parser`) | Read `docs/ralph-wiggum-guide.md` first                                                          |
 | **Orchestrator** | `src/orchestrator-loop.ts`, `-planner`, `-verifier`                                                    | Read `docs/orchestrator-loop-architecture.md` first                                              |
@@ -151,23 +167,23 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 | **Agents**       | `src/subagent-watcher.ts` ★, `team-watcher`, `bash-tool-parser`, `transcript-watcher`, `workflow-run-watcher` | `workflow-run-watcher` is STANDALONE and never touches `subagent-watcher`                        |
 | **AI**           | `src/ai-checker-base.ts`, `ai-idle-checker.ts`, `ai-plan-checker.ts`                                   |                                                                                                  |
 | **Tasks**        | `src/task.ts`, `task-queue.ts`, `task-tracker.ts`                                                      |                                                                                                  |
-| **State**        | `src/state-store.ts`, `run-summary.ts`, `session-lifecycle-log.ts`                                     |                                                                                                  |
-| **Infra**        | `src/hooks-config.ts`, `push-store`, `tunnel-manager`, `image-watcher`, `file-stream-manager`, `remote-hosts` + `remote-reconnect` (pure), `docker-hosts` + `docker-export` | Remote/docker case overlays; see Key Patterns                                                    |
+| **State**        | `src/state-store.ts`, `run-summary.ts`, `session-lifecycle-log.ts`, `intent-store.ts`, `tab-layout.ts` (pure model) + `-service` (sole mutation boundary) + `-persistence` + `-legacy-order`                                     |                                                                                                  |
+| **Infra**        | `src/hooks-config.ts`, `push-store`, `tunnel-manager`, `image-watcher`, `file-stream-manager`, `remote-hosts` + `remote-reconnect` + `remote-wake` (IO: `dgram`/`net`/`child_process`), `docker-hosts` + `docker-export` | Remote/docker case overlays; see Key Patterns                                                    |
 | **Web tabs**     | `src/webview-store.ts`, `webview-capabilities.ts`, `src/web/webview-proxy.ts` (pure), `src/web/routes/webview-routes.ts` | Dashboard URLs as tabs; NOT a SessionMode                                                        |
 | **Search**       | `src/search-service.ts`                                                                                | Pure in-memory core for `GET /api/search`                                                        |
 | **Attachments**  | `src/attachment-registry.ts`, `attachment-magic`, `generated-artifact-attachments`, `session-attachment-history`, `document-preview-cache`, `document-thumbnailer`, `document-conversion-limiter`, `config/attachment-guard` | See Key Patterns                                                                                 |
 | **Plan**         | `src/plan-orchestrator.ts`, `src/prompts/*.ts`, `src/templates/` (`claude-md.ts` + `case-template.md`) | `templates/` holds the CLAUDE.md scaffold generated into new cases                                |
-| **Web**          | `src/web/server.ts` ★, `sse-events.ts`, `routes/*.ts` (20 modules + barrel; `session-routes.ts` ★), `route-helpers.ts`, `ports/*.ts`, `middleware/auth.ts`, `schemas.ts`, `self-update.ts`, `plan-usage-latest.ts`, `ws-connection-registry.ts`, `heic-jpeg-converter.ts` + `heic-jpeg-worker.ts` |                                                                                                  |
-| **Frontend**     | `src/web/public/app.js` (~5K lines, core) + 25 modules + `sw.js`                                       | See Frontend section for the load order, which is authoritative                                  |
-| **Types**        | `src/types/index.ts` (barrel) → 20 domain files; also `src/types.ts` root re-export                    | See `@fileoverview` in index.ts                                                                  |
+| **Web**          | `src/web/server.ts` ★, `sse-events.ts`, `routes/*.ts` (one module per domain + barrel; `session-routes.ts` ★), `route-helpers.ts`, `ports/*.ts`, `middleware/auth.ts`, `schemas.ts`, `self-update.ts`, `plan-usage-latest.ts`, `ws-connection-registry.ts`, `heic-jpeg-converter.ts` + `heic-jpeg-worker.ts` |                                                                                                  |
+| **Frontend**     | `src/web/public/app.js` (core) + the modules listed in the Frontend load order + `sw.js` (+ `voice-pcm-worklet.js`, fetched from JS, not in the load order) | See Frontend section for the load order, which is authoritative                                  |
+| **Types**        | `src/types/index.ts` (barrel) → domain files; also `src/types.ts` root re-export                    | See `@fileoverview` in index.ts                                                                  |
 
 ★ = Large, central file (>50KB) — read its `@fileoverview` first. All files have `@fileoverview` JSDoc — read that before diving in. Discovery aid: `grep -l '@fileoverview' src/web/routes/*.ts` lists all route modules; same grep works for `src/types/`, `src/web/public/*.js`.
 
 **Local packages**: `packages/xterm-zerolag-input/` (local echo overlay, single-source, see Gotchas). `packages/gesture-control/` (`codeman-gesture-control`, hand-tracking overlay source, built via `npm run build:gesture`).
 
-**Config**: `src/config/` — 17 files, no barrel (`index.ts`) exists; import from the specific file.
+**Config**: `src/config/` — flat files plus the `cli-registry/` subdir, no barrel (`index.ts`) exists; import from the specific file. ⚠️ There are TWO `config/` directories: the repo-root `config/` holds tooling only (ESLint, knip, the vitest configs, `test-suites.ts`), while runtime config lives in `src/config/`. Throughout this file a bare `config/<name>.ts` in a code context means `src/config/<name>.ts`.
 
-**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap` (⚠ NOT in the barrel — import from `./utils/lru-map.js` directly), `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver`/`codex-cli-resolver`/`gemini-cli-resolver` (CLI path resolution), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority).
+**Utilities**: `src/utils/` — re-exported via index. Key: `CleanupManager`, `LRUMap` (⚠ NOT in the barrel — import from `./utils/lru-map.js` directly), `StaleExpirationMap`, `BufferAccumulator`, `stripAnsi`, `Debouncer`, `KeyedDebouncer`. Also: `claude-cli-resolver`/`opencode-cli-resolver`/`codex-cli-resolver`/`gemini-cli-resolver`/`antigravity-cli-resolver`/`pi-cli-resolver`/`grok-cli-resolver`/`deepseek-cli-resolver`/`omp-cli-resolver` (CLI path resolution, one per `SessionMode`, all nine sharing the lookup chain in `cli-executable-resolver`: server PATH, then that CLI's install dirs, then an interactive login shell LAST, since it is the only step that spawns anything and it is what finds nvm/Homebrew installs under a service manager's minimal PATH; ⚠ `pi-`, `grok-` and `deepseek-cli-resolver` additionally probe the binary's identity, since `pi` is a generic name, `grok` has npm squatters, and Debian ships an unrelated `dsh`), `file-query` (⚠ Files-panel search matcher, glob-by-two-pointer, never RegExp), `string-similarity` (fuzzy matching), `regex-patterns` (ANSI/token/spinner patterns), `assertNever` (exhaustive checks), `token-validation` (auth tokens), `nice-wrapper` (process priority), `shell-resolver` (⚠ resolves a real login shell for `mode: 'shell'`; the literal string `$SHELL` used to be expanded by the SERVER's shell, which is empty in a container), `event-loop-monitor` (a sync `execSync` freezes the port while the process stays alive, leaving no trace), `dependency-checker` + `dependency-report` (the `codeman doctor` probe engine, registry in `config/dependency-registry.ts`).
 
 ### Data Flow
 
@@ -180,45 +196,116 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 **Input**: `session.writeViaMux()` for programmatic/curl input via tmux `send-keys -l` + `send-keys Enter`, single-line only. Interactive **browser** input goes through a durable **exactly-once** layer: a stable `clientId` + monotonic per-session `seq` persisted to localStorage until the server ACKs, so a dropped link cannot lose or double-deliver a prompt. `ws-connection-registry.ts` supersedes only same-TAB reconnects, so two tabs on one session coexist. → [architecture-invariants#input-delivery-and-ws-resilience](docs/architecture-invariants.md#input-delivery-and-ws-resilience)
 
+**Agent wait primitives**: bounded long-polls: `GET /api/sessions/:id/wait`, `GET .../wait-output` (literal substring, **never** regex) and `wait`/`waitTimeout` on `POST .../input`. Registry `session-wait-registry.ts` (pure), bounds `config/agent-wait.ts`. ⚠️ A timeout is a 200 (`wait.timedOut`). ⚠️ `stop`/`blocked` exist for `claude` and `deepseek` ONLY (rule lives in `hooksAvailableForMode()`): explicit request elsewhere is a 400. ⚠️ Send-and-wait registers the waiter BEFORE the write; teardown must `notifySignal('exit')` BEFORE `cancelAll()`; hangup abort listens on `reply.raw` (guarded by `writableFinished`), never `req.raw`; liveness comes from `isPaneDead`, never `session.pid`. ⚠️ Signals are edge-triggered with no history: gather fan-outs via send-and-wait or `wait-output` markers. Packaged as the `skills/codeman` skill (`codeman skill install`, plugin marketplace, or injection behind `agentSkillEnabled`, SYNCED, default OFF): injection is add-only, marker-owned (`applyAgentSkill`), refuses symlinks, and refreshes a marker-owned user-level copy (`refreshUserAgentSkill`). → [architecture-invariants#agent-wait-primitives](docs/architecture-invariants.md#agent-wait-primitives), `docs/api-reference.md`
+
+**Agent-created case marker** (`src/agent-case-marker.ts`): a case dir that `POST /api/quick-start` CREATES for an agent-driven spawn (signal: the preamble's `X-Codeman-Agent-Origin` header / `agentOrigin` field, else a resolved `parentSessionId`) gets `.codeman-agent-case.json`, published as `agentCreated` on `GET /api/cases`; `GET /api/cases/agent-created` is the cleanup listing (`inUse`, `modifiedAt`) behind Add Case → Manage. ⚠️ Only the branch that CREATES the directory may write it: never label a linked case, cloned repo or pre-existing path (it drives a recursive delete). ⚠️ Reading is total: anything but a well-formed v1 marker reads as not agent-created. ⚠️ Removal stays on `DELETE /api/cases/:name` (the ONE recursive-delete path), and the sweep excludes `inUse` cases. ⚠️ Changing the preamble's headers requires bumping `CODEMAN_PREAMBLE`. → [architecture-invariants#agent-created-case-marker](docs/architecture-invariants.md#agent-created-case-marker)
+
+**Agent preamble cache GC**: the §0 preamble seeded per claude session (`$XDG_CACHE_HOME/codeman-agent-<id>.sh`) is now REMOVED with the session (`removeAgentSessionPreamble` from `_doCleanupSession`, `killMux` only — a detach leaves the session recoverable and its agent would come back to a loader whose file we deleted) and swept at boot (`pruneAgentSessionPreambles(this.sessions.keys())`, once, after restore, so every session this instance owns is in the keep set). Nothing removed them before: 236 leftovers measured on a working machine, the oldest three weeks old. ⚠️ The sweep needs BOTH guards — never a live session's file at any age (the two-line loader reads it mid-run), and `AGENT_PREAMBLE_MAX_AGE_MS` (7d) of age on top, which is what keeps ANOTHER instance's sessions (whose ids this process cannot see) out of the blast radius. Losing one is degradation, not breakage: the §0 fallback block rewrites it. Tests live with the seed's in `test/agent-skill.test.ts`.
+
 **Idle detection**: Multi-layer (completion message → AI check → output silence → token stability). See `docs/respawn-state-machine.md`.
 
+⚠️ **A `❯` sighting is NOT the end of a turn, and neither is silence.** Claude redraws the composer all through a turn, and its working line (`✻ Actualizing… (13m 23s · …)`) is invisible to `SPINNER_PATTERN`, keyword lists and the raw stream. `_confirmIdle()` (session.ts) requires the pane to go quiet AND the SCREEN (`capturePaneText()` + the working-line pattern) to agree; a sustained run of repaints (`session-activity.ts`) marks a turn as started. ⚠️ The composer glyph and working line are per-CLI registry DATA (`capabilities.workDetect`), never Claude constants; a CLI declaring neither falls back to Claude's pair. ⚠️ `workingLine` is config-supplied and runs on the PTY hot path, so it must compile through `compileVersionRegex()` in BOTH the schema refine and `_workingLinePattern()` (ReDoS guard; null, not throw). → [architecture-invariants#idle-detection-composer-glyph-and-working-line](docs/architecture-invariants.md#idle-detection-composer-glyph-and-working-line)
+
+⚠️ **A turn that ENDED waiting for its own workers is working, not idle.** Claude closes such a turn with `✻ Waiting for 1 dynamic workflow to finish` (background agents / ultracode) and resumes by itself; `capabilities.workDetect.awaitingLine` makes the idle probe count it as work. ⚠️ Claude never redraws that row, so it stays on screen after the workers finish: test it ONLY as the newest column-0 row above the composer (`isAwaitingWorkers()`), never pane-wide and never on the stream. → [architecture-invariants#idle-detection-composer-glyph-and-working-line](docs/architecture-invariants.md#idle-detection-composer-glyph-and-working-line)
+
+⚠️ **A quiet pane is not always a pane that wants you.** A CLI can declare an optional `capabilities.workDetect.watchingLine` (a monitor, background shell or cloud hand-off it is still running); the idle probe reads it into `Session.watching` and `notePrompt()` opens that idle item ALREADY acknowledged, so no surface alerts. Only `idle` is eligible, and the label is pane-derived and prompt-injectable, so a pattern must anchor on chrome only that CLI draws. → [architecture-invariants#the-watching-signal-a-quiet-pane-that-is-not-waiting-for-you](docs/architecture-invariants.md#the-watching-signal-a-quiet-pane-that-is-not-waiting-for-you). Tests: `test/session-watching.test.ts`, `test/watching-no-alert.test.ts`.
+
+**An exited agent in a live pane** (`paneExit`, #446): panes use `remain-on-exit on`, so `/exit` leaves a pane, session and pid that look alive; `TmuxManager.startPaneExitWatcher()` publishes `SessionState.paneExit` via `session:updated`. ⚠️ Never set `status: 'error'` or null the `pid` for it; the field is TRI-STATE (absent = UNKNOWN, never alive, scoped by `Session.paneExitApplies`); an absent `#{pane_dead_status}` is not 0; a path that starts a command in a pane must clear the record AND persist. A clean exit is CLOSED via `cleanupSession()` (`pane-exit-sweep.ts`): only an explicit numeric status 0 with no signal, confirmed by 2 reads, with no start/attach in flight (`paneLifecycleInFlight`) and not within 10 s of one (a startup error keeps its row); a crashed agent keeps its row. → [architecture-invariants#an-exited-agent-in-a-live-pane-paneexit](docs/architecture-invariants.md#an-exited-agent-in-a-live-pane-paneexit)
+
+**Dead-pane respawn resume pin** (`_buildRespawnPaneOptionsWithResumePin()`, session.ts): recovering a dead pane, like a custom-model `restartCli()`, must pin the conversation or claude refuses the reused `--session-id`. The pin takes the first transcript-backed candidate (chain tail, launch seed, own id), never `_claudeSessionId`, adds nothing when none is backed, and is never applied to remote or docker sessions. → [architecture-invariants#dead-pane-respawn-the-resume-pin](docs/architecture-invariants.md#dead-pane-respawn-the-resume-pin)
+
+**Workspace-trust dialog auto-accept** (`session-trust-dialog.ts`, pure): Claude Code's per-directory trust dialog is always answered yes, or the session is stuck. ⚠️ Match the compacted SCREEN (`compactScreenText()`, all whitespace removed), never the stream (tmux sends words joined by cursor-forwards, not spaces). ⚠️ Never answer with a blind `\r` (newer versions highlight "No, exit" first): `trustDialogNextKey()` returns ONE key per re-read frame (arrow, then Enter only once `❯` is on the trust option), and the LAST marked option wins. ⚠️ All three guards must hold: startup window `TRUST_DIALOG_WINDOW_MS` (90s), two-marker match (`isTrustDialogScreen`), attempt cap `TRUST_DIALOG_MAX_ATTEMPTS` (6). ⚠️ Read `capturePaneText()`; only a direct-PTY session falls back to a SHORT buffer tail. ⚠️ The scan must schedule its own next read (`_trustDialogTimer`, cleared in `_clearAllTimers()`), not rely on PTY output. → [architecture-invariants#workspace-trust-dialog-auto-accept](docs/architecture-invariants.md#workspace-trust-dialog-auto-accept)
+
+**Process-tree walks are bounded** (`proc-tree.ts`, pure): `collectDescendants(pid, byParent)` is the ONE descendant traversal, fed by one cached `ps -eo pid=,ppid=` snapshot (`refreshProcSnapshot()` in tmux-manager.ts: async, in-flight-shared, and ANY error discards the result rather than caching a truncated `ps`). ⚠️ Never walk a process tree with per-node `pgrep` or unbounded recursion (the unbounded version took a machine down): the walk must terminate on cycles, cap depth (`PROC_WALK_MAX_DEPTH`) and node count (`PROC_WALK_MAX_NODES`), and never spawn anything. ⚠️ Keep it in its own module so the test exercises the shipped code, and report truncation through `onTruncated` naming both caps, never silently. → [architecture-invariants#process-tree-walks-are-bounded](docs/architecture-invariants.md#process-tree-walks-are-bounded)
+
 **Auto-resume on usage limit** (opt-in per session, top of the Respawn tab): when Claude halts on a subscription limit, `usage-limit-patterns.ts` (pure, unit-tested) parses the reset time and `SessionAutoOps` arms a timer for reset+2min, then sends Esc + `continue`. ⚠️ Respawn cycles are blocked while paused (`isLimitPaused` guard in `onIdleDetected`), which is what prevents `/clear` from wiping the paused conversation. Claude-mode only. → [architecture-invariants#auto-resume-on-usage-limit](docs/architecture-invariants.md#auto-resume-on-usage-limit)
 
-**Plan-usage chip** (statusLine telemetry, `showPlanUsageLimits`, per-device: desktop default **ON**, handhelds OFF via the mobile block in `getDefaultSettings()`): resolve it ONLY through `planUsageChipEnabled()` in settings-ui.js, which backs all three call sites (the App Settings checkbox, the chip's visibility, and the `statusLineTelemetry` flag on session create). A chip shown without telemetry renders `—` forever. Codeman injects its own `statusLine.command` exporter which POSTs Claude's `rate_limits` blob to `POST /api/status-telemetry`. The exporter is identified by a marker, so it only ever adds/updates/removes a statusLine that is **ours**, never a user's hand-authored one, and it prints the footer through so the in-terminal statusline is not blanked. Claude-mode only; distinct from auto-resume, which reacts to the limit *message* rather than showing live %. → [architecture-invariants#plan-usage-chip-statusline-telemetry](docs/architecture-invariants.md#plan-usage-chip-statusline-telemetry), `docs/usage-limits-display-plan.md`
+**Plan-usage chip** (`showPlanUsageLimits`, per-device: desktop default **ON**, handhelds OFF): resolve DISPLAY only through `planUsageChipEnabled()` (settings-ui.js). The same setting is the server-side COLLECTION switch, read fresh by `readPlanUsageTelemetryEnabled()` (hooks-config.ts) at every claude create/respawn. ⚠️ An ABSENT key reads as ON in the reader; `GET /api/settings` must never write. ⚠️ A save sends `showPlanUsageLimits` ONLY when it flips the chip on that device (`planUsageCollectionFlip()`), or a phone switches collection off for every desktop. Claude data comes from the statusLine exporter, injected as an EPHEMERAL `claude --settings` flag (`resolveStatusLineCliCommand`), never written to disk, WRAPPING a user's own statusLine, posting to `POST /api/status-telemetry`. Codex comes from a read-only `account/rateLimits/read` poll (main bucket only). → [architecture-invariants#plan-usage-chip-statusline-telemetry](docs/architecture-invariants.md#plan-usage-chip-statusline-telemetry), `docs/usage-limits-display-plan.md`
 
 **Orchestrator**: State machine that turns a user goal into a phased plan and drives it to completion: `idle → planning → approval → executing → verifying → (replanning) → completed/failed`. `OrchestratorLoop` (engine) delegates plan generation to `orchestrator-planner` and per-phase verification gates to `orchestrator-verifier`, executing phases via team agents/`task-queue`. State persists under the `orchestrator` key in `state.json`. Distinct from Ralph (single-session autonomous loop) — orchestrator coordinates multi-phase, multi-agent execution. See `docs/orchestrator-loop-architecture.md`.
 
 **Cron (`CronJob`s)**: saved, named jobs on a recurring schedule (`once`/`interval`/`daily`/`weekly`) with per-job run history. ⚠️ **Distinct from the legacy `ScheduledRun`** (`/api/scheduled`, a run-now duration-bounded loop); the two never interact and keep separate `Scheduled*` / `Cron*` names. `CronService` **reuses the existing session layer** rather than rebuilding tmux logic. Next-run math is pure and unit-tested in `cron-time.ts` (server-local timezone). The schedule is advanced BEFORE launch so a slow launch cannot re-trigger. → [architecture-invariants#cron-jobs](docs/architecture-invariants.md#cron-jobs), `docs/cron-discovery.md`
 
-**Remote sessions + remote SSH cases**: a case can point at a remote host. The agent runs inside a durable remote `tmux -L codeman-remote` (session name `codeman-ssh-<id>`, deliberately failing the remote Codeman's `SAFE_MUX_NAME_PATTERN` so an instance on the target host never adopts it), fronted by a LOCAL tmux pane running `ssh`. Attached (`owned:false`) sessions **detach, never kill** on tab close; owned ones propagate `kill-session`. A bounded-backoff watcher auto-reconnects dropped sessions (`remoteAutoReconnect`, default ON). ⚠️ **Command-injection surface: every ssh command line must flow through `buildSshConnectionArgs()`**, which `shellescape`s every user field. Never hand-build an ssh line elsewhere. ⚠️ Run flows must route remote cases through `POST /api/quick-start`, not `POST /api/sessions` (which stat-validates `workingDir` locally and has no `caseName`). → [architecture-invariants#remote-sessions-over-ssh](docs/architecture-invariants.md#remote-sessions-over-ssh), [#remote-ssh-cases](docs/architecture-invariants.md#remote-ssh-cases), `docs/remote-sessions.md`
+**Remote sessions + remote SSH cases**: a case can point at a remote host. The agent runs in a durable remote `tmux -L codeman-remote`, fronted by a LOCAL tmux pane running `ssh`. Attached (`owned:false`) sessions **detach, never kill**; owned ones propagate `kill-session`. Auto-reconnect (`remoteAutoReconnect`, default ON) revives ONLY when `remoteTmuxSessionAlive()` proves the remote session alive. ⚠️ Classify that probe by EXIT STATUS (`classifyRemoteAliveExit`), never stdout. ⚠️ **Command-injection surface: every ssh command line must flow through `buildSshConnectionArgs()`**; never hand-build one. ⚠️ Remote file reads (`src/remote-files.ts`, attachment routes too) take browser paths only as `shellescape`d tokens, resolve symlinks fail-closed, cap on the REMOTE size, never copy to local disk, are bounded by `src/remote-ssh-limiter.ts`, and pick the host from the SESSION, never the path; no writes over ssh (the `PUT` guard must precede local path validation). ⚠️ Route remote cases through `POST /api/quick-start`, not `POST /api/sessions`. → [architecture-invariants#remote-sessions-over-ssh](docs/architecture-invariants.md#remote-sessions-over-ssh), [#remote-ssh-cases](docs/architecture-invariants.md#remote-ssh-cases), `docs/remote-sessions.md`
 
-**Docker cases**: a case can point at a **container**, with any of the five CLI backends running inside it. Like remote-SSH this is a **LOCATION OVERLAY on cases, never a sixth `SessionMode`**. Exactly one long-lived container **per case**, shared by all its sessions, so killing a session kills only that session's in-container tmux and **never** `docker stop` while siblings remain. The workspace is a real host dir bind-mounted at the **same absolute path**, which is what keeps file-routes/watchers on real host bytes and makes the in-container transcript projHash match the host. Credentials are **seeded** (RO mount, copied into the container once) rather than shared RW, so in-container CLIs never write refreshed tokens back to the host, and bind mounts are excluded from `docker commit` so exports stay secret-free. **NEVER a create-time `-e` for secrets, NEVER `--privileged`, NEVER the docker socket.** Config drift is detected via a label hash and a drifted launch is REFUSED rather than silently launched with stale config. ⚠️ On the loopback-only prod bind a container cannot reach 127.0.0.1, so in-container hooks need `CODEMAN_DOCKER_BRIDGE_HOOKS=1`; otherwise idle detection falls back to output-based. → [architecture-invariants#docker-cases](docs/architecture-invariants.md#docker-cases), `docs/docker-cases.md` (user guide), `docs/docker-cases-plan.md` (design)
+**Wake-on-LAN (`remote-wake.ts`)**: optional `RemoteHost.wakeMac` (magic packet) or `RemoteHost.wakeCommand` (single executable, no shell, takes precedence) lets HTTP input, `POST /api/sessions/:id/wake` and the user's create/attach (`ensureHostAwake`) wake a sleeping host. ⚠️ Only an explicit user request may wake: never give the registry to the auto-reconnect watcher, `handleRemoteSessionDropped`, boot recovery or `cron-service.ts`, and `GET /api/sessions/:id/reachability` must never wake. ⚠️ Detection is a throttled bare TCP probe; never add `ServerAliveInterval`, and a `jumpHost`/`socksProxy`/`ProxyCommand` host is reachability-UNKNOWN (`isProbeable()`): never buffer, gate or banner on it. ⚠️ In multi-user mode a non-admin attach 403s BEFORE host lookup. ⚠️ WS keystrokes bypass the registry, so the banner (`host-wake-ui.js`) must not promise queued input. Waiting requests use the 40 s `REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS`. → [architecture-invariants#remote-ssh-cases](docs/architecture-invariants.md#remote-ssh-cases)
 
-**External CLI modes (OpenCode, Codex, Gemini, Antigravity)**: `isExternalCliMode()` in `session.ts` gates Claude-specific behavior off (Ralph tracker, BashToolParser, token/CLI-info parsing, ❯-prompt readiness); these CLIs render their own TUIs, so readiness is output stabilization instead. All four **require tmux with no direct PTY fallback**, because secrets are injected via socket-scoped `tmux setenv` and never on the spawn command line. ⚠️ `run*()` in `session-ui.js` MUST unwrap the `{success,data}` envelope; reading the raw shape silently breaks the run. → [architecture-invariants#external-cli-modes-opencode-codex-gemini](docs/architecture-invariants.md#external-cli-modes-opencode-codex-gemini)
+**Docker cases**: a case can point at a **container** running any CLI mode inside it, a **LOCATION OVERLAY on cases, never a `SessionMode`**. One long-lived container **per case**, shared by its sessions: killing a session kills only its in-container tmux, **never** `docker stop` while siblings remain. The workspace is bind-mounted at the **same absolute path**. Credentials are **seeded**, never shared RW. **NEVER a create-time `-e` for secrets, NEVER `--privileged`, NEVER the docker socket.** A drifted config (label hash) REFUSES the launch. ⚠️ An **adopted** container (`DockerCase.owned === false`) is only `exec`ed into: never create, start, stop, restart, remove, `docker commit` or `docker pause` it; fail closed. Test `owned === false`, never truthiness. ⚠️ Apply `owned` AFTER `dockerConfigHash`. ⚠️ Run modes come from the CONTAINER (`availableModes`), and a failed probe is normal for an OWNED case. ⚠️ Root exec user drops the bypass flag via the registry's `overlays.docker.rootCommand`, never a branch. ⚠️ Adoption is admin-only in multi-user mode. ⚠️ Loopback prod needs `CODEMAN_DOCKER_BRIDGE_HOOKS=1` for in-container hooks. → [architecture-invariants#docker-cases](docs/architecture-invariants.md#docker-cases), `docs/docker-cases.md`
 
-**Run launch synchronization**: the Run entrypoint holds an in-flight lock and disables `#runBtn` for the whole launch (≥500ms), so a double click cannot create duplicate sessions with the same `w<n>-<case>` name. `_ensureCreatedSessionVisible()` runs before `selectSession()`, and `_onSessionCreated()` stays an idempotent upsert, so POST-first and SSE-first ordering both produce exactly one rendered tab. → [architecture-invariants#run-launch-synchronization](docs/architecture-invariants.md#run-launch-synchronization)
+**Docker Compose deployment** (`docker/`): Codeman runs in a container and spawns Docker cases as **SIBLING** containers via the host socket, never nested. `resolveDockerDaemonMountSource()` maps HOME bind sources into the daemon's namespace (`CODEMAN_DOCKER_HOST_HOME`); `CODEMAN_CASES_PATH` makes workspaces resolve to the same absolute path on both sides. ⚠️ `CODEMAN_CASES_PATH` must move every consumer: resolve it only via `config/cases-dir.ts`. ⚠️ `.dockerignore` matches whole paths: keep `**/.env` or `docker/.env` secrets ship in the image. ⚠️ Long-form binds create missing sources ROOT-OWNED: `Start-Codeman.sh` pre-creates them, and `docker/entrypoint.sh` (root, `cap_add: [CHOWN, DAC_OVERRIDE, KILL, SETGID, SETUID]` against `cap_drop: ALL`, `KILL` for tini; pinned by the test) fixes ownership then drops to `PUID:PGID` via `setpriv`, never re-owning foreign dirs. ⚠️ Append `/opt/codeman-cli` and `~/.local/bin` to `PATH`, never prepend. ⚠️ `server.Dockerfile`, the compose file and `.env.example` feed the self-updater's environment gate (`docs/docker-self-update.md`). → [architecture-invariants#docker-compose-deployment](docs/architecture-invariants.md#docker-compose-deployment), `docs/docker-compose.md`
 
-**Unified session list**: `GET /api/sessions/unified` merges live sessions, persisted state, lifecycle-log history, and Claude transcript files into one deduped list (pure core in `src/services/unified-session-service.ts`). Transcript rows fold into their owning session via a `claudeSessionId → Codeman id` alias map, so resumed and `/clear`-respawned sessions do not appear twice. No terminal buffers in the response, unlike `/api/sessions`. Backs the Cmd+K Session Manager, plus pinning and cross-device tab order (`PUT /api/session-order`; pure merge helpers in `src/session-order.ts`, pushing device wins and server-only ids are never dropped). → [architecture-invariants#unified-session-list-and-session-manager](docs/architecture-invariants.md#unified-session-list-and-session-manager)
+**CLI registry** (`src/config/cli-registry/`): every run mode is a `CliEntry` (discovery, launch argv template, env handling, `capabilities`, and the `overlays` behind remote/docker pane commands). **No code outside `stock.ts` may branch on a CLI id**: use a capability field or a NAMED PROFILE (`profiles.ts`); `test/cli-registry-no-id-branching.test.ts` and `test/frontend-cli-no-id-branching.test.ts` enforce it. ⚠️ Config holds typed argv tokens, never shell text; literals are validated at LOAD time and a bad one rejects the whole entry. ⚠️ Keep `external`, `hooks` and `altScreen` independent; never derive one from another. ⚠️ Config regexes (`discovery.version.regex`, `capabilities.workDetect.workingLine`, `capabilities.workDetect.watchingLine`, `capabilities.workDetect.awaitingLine`) must compile through `compileVersionRegex()`. ⚠️ `privilegedParams[].param` names a LAUNCH PARAM, not the legacy `<Mode>Config` field (bridged only by `launch.legacyConfigAliases`); a wrong name silently clamps nothing. ⚠️ Resolve the registry AT CALL TIME, never in a module-level const. ⚠️ Remote claude/omp arms of `buildRemoteLaunchCommand` are not covered by the pane-command golden. `~/.codeman/clis.json` overrides entries. It is WRITTEN only by the opt-in CLI management routes (`cliManagementEnabled`, default OFF; `/api/clis`, `cli-registry-routes.ts`), and only through `mutateRegistryFile()` in `registry-writer.ts`, which serializes mutations and refuses (409) a file that does not parse or has group/world permission bits rather than overwriting it. Importing the registry still writes nothing. → [architecture-invariants#cli-registry](docs/architecture-invariants.md#cli-registry), `docs/cli-registry.md`
 
-**Hook events**: Claude Code hooks trigger via `/api/hook-event`. Key events: `permission_prompt`, `elicitation_dialog`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`. See `src/hooks-config.ts`; upstream hook semantics mirrored in `docs/claude-code-hooks-reference.md`.
+**External CLI modes (OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek, OMP)**: `isExternalCliMode()` in `session.ts` gates Claude-specific behavior off (Ralph tracker, BashToolParser, token parsing, ❯ readiness; readiness is output stabilization); work detection is per-CLI `capabilities.workDetect` data, not this gate. All eight **require tmux, no direct PTY fallback** (secrets go via socket-scoped `tmux setenv`, never the command line). ⚠️ `run*()` in `session-ui.js` MUST unwrap the `{success,data}` envelope. ⚠️ **Codex uses predictive write-through echo, never the buffer overlay**: `_predictHookOnData` must never `return` (wire path stays byte-identical), and flushed text and a bracketed paste must go out as separate delayed writes. ⚠️ **Pi**: no bypass flag, never invent one; `approveProjectTrust` executes repo code, so it is in the clamp's **materialize** branch; never wire `--api-key`. ⚠️ **Grok**: `alwaysApprove` is stripped for non-granted owners (only-if-sent). ⚠️ **DeepSeek**: the agent is a PROFILE (Run gates on `isDeepSeekRunnable()`); the permission switch is the `DSH_PERMISSION_MODE` env var, so `clampEnvOverridesForOwner()` must DROP `DSH_PERMISSION_MODE`, `DSH_HOME` and `DEEPSEEK_BASE_URL` for non-granted owners; `hooksAvailableForMode()` is per-SESSION for it (pass `sessionHookOptions(session)`) and is never a stand-in for `mode === 'claude'`; answers come from `deepseek-transcript.ts`, paired by header `cwd` + boot window, never newest-mtime. ⚠️ **OMP**: `OMP_AUTH_BROKER_URL`/`_TOKEN` are clamped the same way. → [architecture-invariants#external-cli-modes-opencode-codex-gemini-antigravity-pi-grok-deepseek-omp](docs/architecture-invariants.md#external-cli-modes-opencode-codex-gemini-antigravity-pi-grok-deepseek-omp)
+
+**DeepSeek web UI** (`POST`/`GET`/`DELETE /api/deepseek/web`, `deepseek-web-server.ts`): the Run menu's "DeepSeek web UI..." entry supervises ONE background `dsh web` child process, deliberately **NOT a shell session**. ⚠️ Every piece is load-bearing: exactly one server (a second click REUSES it), restarted when the browser authority changes (`--trusted-host`, last asker wins), killed on shutdown via `stopDeepSeekWeb()` (the detached child would otherwise outlive Codeman and hold its port), and failures returned to the caller. ⚠️ Never hardcode the port: search from 3080 across 40, detect free ports by BINDING, then wait for the server to really answer. ⚠️ Both `POST` and `DELETE` must stay behind `canUsernameRunPrivilegedCommands` (booting a profile runs its plugin code; the server is shared). → [architecture-invariants#deepseek-web-ui](docs/architecture-invariants.md#deepseek-web-ui)
+
+**Custom Model Endpoint Profiles** (opt-in, `customModelEndpointsEnabled`, SYNCED, default OFF; `docs/custom-model-endpoints.md`): points a session at a user-configured OpenAI-compatible endpoint (store `custom-model-hosts.ts`, `~/.codeman/custom-model-hosts.json`, 0600). `authStyle` is `bearer` or `api-key`, never both headers (hangs the server). The per-CLI redirect is registry data, `capabilities.customModelInjection` (`env` / `configContentEnv` / `configDir` / `unsupported`), computed by the pure `custom-model-injection.ts`; ⚠️ `configDir` writes an isolated per-session config, NEVER the user's real `~/.codex`/`~/.pi`/`~/.omp`/grok config. ⚠️ Claude applies via `Session.restartCli()` (a relaunch in the existing pane, so the conversation is pinned as `resumeSessionId`), the rest one-shot at launch; retired env keys must also be `setenv -u`'d (`_pendingEnvUnsets`), since tmux env survives `respawn-pane`. ⚠️ Remote/Docker sessions are refused (400). ⚠️ Persist only KEYS (`__customModel`), never values (they carry the API key). ⚠️ Every redirectable var must be in that CLI's `privilegedEnvKeys`, and `ANTHROPIC_*` stays out of claude's `allowedPrefixes`. ⚠️ The Run-menu picker builds entries from `window.__codemanCustomModelClis` (escaped via `escapeScriptJson()`), never a hardcoded CLI id list, and launches through `run()` via a temporary `_runMode` swap, never `setRunMode()`. → [architecture-invariants#custom-model-endpoint-profiles](docs/architecture-invariants.md#custom-model-endpoint-profiles)
+
+⚠️ **llama-swap endpoints** (one model at a time): the apply routes check `GET /running` and return `requiresConfirmation` before evicting a model another live session uses; `confirmedSwap` and `confirmedContext` are SEPARATE flags and must stay so. Claude alone gets a context floor (`CLAUDE_MIN_SAFE_CONTEXT_TOKENS`); context is parsed from `/running`'s `cmd`, never trusted from `/props`. Backend log lines come from llama-swap's `/api/events` `upstream` source, never `/logs`. → [architecture-invariants#custom-model-endpoint-profiles](docs/architecture-invariants.md#custom-model-endpoint-profiles)
+
+**Run launch synchronization**: the Run entrypoint holds an in-flight lock and disables `#runBtn` for the whole launch (≥500ms) so a double click cannot create duplicate `w<n>-<case>` sessions; `_ensureCreatedSessionVisible()` runs before `selectSession()` and `_onSessionCreated()` stays an idempotent upsert, so POST-first and SSE-first both render exactly one tab. ⚠️ **Closing has the mirror-image race**: `closeSession()` must read `wasActive` BEFORE its `await` and announce the delete via `_closingSessions`, and `_onSessionDeleted` skips the active-session handoff for ids in that set; never read `activeSessionId` after the fact. The fallback picks the first `sessionOrder` entry still in `sessions`. Tests: `test/session-close-fallback.test.ts`. → [architecture-invariants#run-launch-synchronization](docs/architecture-invariants.md#run-launch-synchronization)
+
+**Session lineage lines** (tab → tab it spawned, `sessionLineageLines`, per-device, desktop default ON): a create request may name its spawner via a `parentSessionId` body field or the `X-Codeman-Parent-Session` header; `resolveParentSessionId()` (route-helpers.ts) resolves it (exact id or unique ≥8-char prefix, live, visible, same owner) and ⚠️ anything unresolvable is DROPPED, never a 400. Rides `toState()`, no new SSE event. ⚠️ Rendering is a LAYER on the existing SVG pass (`_appendLineageConnectionLines` at the tail of `_updateConnectionLinesImmediate()`), geometry pure in `computeLineagePath()`: one U-bridge shape hanging from the strip bottom, colors keyed on the SPAWNING tab and memoized (never by draw index). ⚠️ Desktop only (z-index vs the fixed mobile header). ⚠️ Paths must keep `data-agent-id="lineage:<childId>"` (the entrance animation queries it); skip edges whose endpoint is scrolled out of the strip. → [architecture-invariants#session-lineage-lines-tab--tab-it-spawned](docs/architecture-invariants.md#session-lineage-lines-tab--tab-it-spawned)
+
+**Auto-named sessions** (`autoNameSessions`, SYNCED, default OFF): a placeholder tab (`w3-myapp`) takes its first real prompt as a title in the `<prefix>: <title>` form, so the case identity and `w<n>` counter survive. Ownership is `SessionState.nameSource` (`placeholder` | `auto` | `manual`; the `name` setter / `PUT /api/sessions/:id/name` makes it `manual`, never touched again). ⚠️ `applyAutoName()` flips to `auto` even if the string is unchanged, so only the FIRST titled prompt names the tab. ⚠️ Only user input counts: `SessionWriteOptions.fromUser` is set by the browser WS path and `POST /api/sessions/:id/input` ONLY; any new user-input path must set it (and the send-key Shift+Enter path must call `trackUserInput()`). ⚠️ The pure tracker (`session-auto-name.ts`) sits on the raw keystroke stream with an explicit rule per key; add a rule for any new key class. ⚠️ `nameSource` also decides `--name`: only a `manual` name is pinned on the claude CLI (`Session.cliPinnedName`), since `--name` is also the `/resume` title; a rename appends a `custom-title` row to a LOCAL, non-docker transcript, and a same-name PUT is a no-op (never flips to `manual`). Tests: `test/session-auto-name.test.ts`. → [architecture-invariants#auto-named-sessions-first-prompt--tab-title](docs/architecture-invariants.md#auto-named-sessions-first-prompt--tab-title)
+
+**Maintainer bot (external)**: the Telegram bot that reviews open PRs and triages discussion threads in Codeman sessions used to live at `scripts/pr-bot/`. It moved OUT of this repository on 2026-09-14, to `~/codeman-cases/prbot/` (its own private git repo, systemd unit `codeman-pr-bot`, guide + agent rules in its own `README.md` and `CLAUDE.md`). It is a CLIENT of Codeman's HTTP API like any other, so nothing here depends on it and it is not part of the server, the CLI or the npm package. ⚠️ It spawns real sessions named `prbot-<n>` / `dscbot-<n>` on the local Codeman and holds clones under `~/.codeman/pr-bot/`, so those session names and that data dir are taken; it also fetches PR heads into `refs/pr-bot/*` of this checkout and must never check out, reset or clean it. The CHANGELOG entries for 1.25.0 and earlier still describe it, which is history rather than drift.
+
+**Unified session list**: `GET /api/sessions/unified` merges live sessions, persisted state, lifecycle-log history and transcript files into one deduped list (pure core `src/services/unified-session-service.ts`), backing the Cmd+K Session Manager, pinning and cross-device tab order (`PUT /api/session-order`, `src/session-order.ts`). ⚠️ Transcript history is THREE stores (`~/.claude/projects`, `~/.omp/agent/sessions`, `~/.codex/sessions`), folded via the `claudeSessionId → Codeman id` alias map (not Claude-only despite the name). ⚠️ `resumeId` is set by a SCANNER row only, never a live session; every surface that re-projects these rows (phone overview included) must carry it through, or a tap silently starts a second conversation. → [architecture-invariants#unified-session-list-and-session-manager](docs/architecture-invariants.md#unified-session-list-and-session-manager)
+
+**Owner tab layouts** (`tab-layout*.ts` + `GET`/`PUT /api/tab-layout`): named tab GROUPS over the flat strip, scoped per owner (`@single` when multi-user is off), persisted as `tabLayouts` in state.json. BACKEND ONLY: no frontend calls these routes yet. ⚠️ `TabLayoutService` is the single mutation boundary (one completed server action = at most one versioned write); never write layout state from a route or manager directly. ⚠️ The layout PROJECTS onto `PUT /api/session-order` via `tab-layout-legacy-order.ts`; change both sides together. ⚠️ Reconciliation is gated on a SUCCESSFUL restore (`markRestorationComplete`/`assertDeletionReady()`): a failed restore must leave the layout untouched or live tabs get pruned. → [architecture-invariants#owner-tab-layouts](docs/architecture-invariants.md#owner-tab-layouts)
+
+**Hook events**: Claude Code hooks trigger via `/api/hook-event` (`permission_prompt`, `elicitation_dialog`, `elicitation_complete`, `elicitation_response`, `idle_prompt`, `stop`, `teammate_idle`, `task_completed`, `prompt_submitted`); see `src/hooks-config.ts` and `docs/claude-code-hooks-reference.md`. ⚠️ Every claude session installs the hooks block into its workspace (add-only merge) from every create path and from `restoreMuxSessions()`, gated by `workspaceHooksEnabled` (SYNCED, default ON). ⚠️ Route that decision through `applyWorkspaceHooks`, never call `ensureCodemanHooks` at a new site, or the setting silently stops applying. ⚠️ An AskUserQuestion / plan-selection dialog arrives as `permission_prompt` (RED alert), not `elicitation_dialog` (MCP elicitation). → [architecture-invariants#hook-events-and-workspace-hook-installation](docs/architecture-invariants.md#hook-events-and-workspace-hook-installation)
+
+**Reboot restore** (`src/reboot-restore.ts` pure + `web/reboot-restore-registry.ts` + `routes/reboot-restore-routes.ts` + `reboot-restore-ui.js`): after a host reboot kills every pane, Codeman holds an IN-MEMORY plan of the destroyed sessions and a banner offers to rebuild them. ⚠️ The heuristic only decides whether to ASK. ⚠️ Rebuild is TAKE-then-build (entries leave the plan before the first `await`, single-flighted per owner). ⚠️ Re-check grant, workspace and already-live at click time, reading already-live FRESH per entry; key confinement on the entry's OWNER, never the caller. ⚠️ Rebuilt sessions come back disarmed: no respawn/Ralph, `rearmAutoResumeSchedule: false`, and pass `nameSource` through. ⚠️ Undo a failed rebuild with `discardPartiallyBuiltSession()`, NEVER `cleanupSession()`. Claude-mode only, never remote/docker. Tests: `test/reboot-restore.test.ts`. → [architecture-invariants#reboot-restore](docs/architecture-invariants.md#reboot-restore)
+
+**Approvals Inbox** (`approvalsInboxEnabled`, SYNCED, default OFF; the store and answer endpoints run regardless): `web/approval-inbox.ts` is an in-memory, claude-only queue fed by `/api/hook-event`, at most ONE item per session, answered via `POST /api/approvals/:id/answer` through `writeViaMux` (menu answers never carry `\r`). ⚠️ Accept `option` digits ONLY if they match options parsed from a fresh RE-CAPTURE of the pane; a dialog no longer on screen is a 409. ⚠️ Resolve permission/question items only via the pane-verified `verifyStillAnswerable()`; the heuristic `working` signal alone may resolve `idle` items only. ⚠️ `applyCapture()` is ADD-ONLY for `options`. ⚠️ Viewing ACKNOWLEDGES an idle item (never resolves it) and only a human selection does: app-made selections pass `selectSession(id, { auto: true })`; `_ackDelivery` spends the IDLE alert only. ⚠️ `handleInit` seeds tab alerts from `GET /api/approvals` REGARDLESS of the setting. → [architecture-invariants#approvals-inbox](docs/architecture-invariants.md#approvals-inbox)
+
+**Read My Mind intent profiles** (`readMyMindEnabled`, SYNCED, default OFF; `docs/readmymind-plan.md`): per-CASE profiles (goals + recent prompts) keyed by owner + realpath(workingDir), captured from the transcript (`transcript:user_prompt`), never the input paths; the listener must stay inside `startTranscriptWatcher()`'s `if (!watcher)` block. Store `src/intent-store.ts` → `intents.json`, ⚠️ written 0600 tmp+rename and never fed to `/api/search` (prompts carry secrets). Routes in `readmymind-routes.ts` (ownership via `findSessionOrFail` WITH `req`); predictor = pure `readmymind-context.ts` + IO in `readmymind-collectors.ts` + `readmymind-predictor.ts`, claude-only, one in flight per session (409). ⚠️ Suggestions render via value/`textContent` ONLY and nothing auto-sends, ever. Frontend `readmymind-ui.js`. → [architecture-invariants#read-my-mind-intent-profiles](docs/architecture-invariants.md#read-my-mind-intent-profiles)
+
+**Voice dictation via Claude** (`claudeVoiceEnabled`, SYNCED, default OFF): the mic transcribes through this machine's Claude Code login (the CLI `/voice` backend) instead of Deepgram; the browser captures, `src/web/voice-stream.ts` relays to Anthropic. ⚠️ The OAuth token never reaches the page. ⚠️ Credentials are READ-ONLY (`src/claude-credentials.ts`): never refresh them (it rotates the refresh token and can sign the user out of their CLI). ⚠️ Capture must be linear16/16 kHz/mono via an AudioWorklet; `voice-pcm-worklet.js` borrows voice-input.js's `?v=` token, so edit the two together. ⚠️ Claude transcript frames are cumulative: replace, never append. → [architecture-invariants#voice-dictation-via-claude](docs/architecture-invariants.md#voice-dictation-via-claude)
 
 **Agent Teams**: `TeamWatcher` polls `~/.claude/teams/`, matches to sessions via `leadSessionId`. Teammates are in-process threads appearing as subagents. Enable: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. See `docs/agent-teams/`.
 
 **Circuit breakers**: the Ralph breaker prevents respawn thrashing (`CLOSED` → `HALF_OPEN` → `OPEN`; reset via `/api/sessions/:id/ralph-circuit-breaker/reset`). **Distinct: the PTY-exit breaker** (`session-pty-exit-breaker.ts`) trips after repeated rapid PTY exits and blocks auto-restarts. ⚠️ It resets ONLY via an explicit `{clearBreaker:true}` body on `POST /api/sessions/:id/interactive`; the frontend's auto-reattach in `selectSession()` sends no body and must never clear it. → [architecture-invariants#circuit-breakers-ralph--pty-exit](docs/architecture-invariants.md#circuit-breakers-ralph-and-pty-exit)
 
-**Full-scrollback replay**: `GET /api/sessions/:id/terminal?full=1` returns the entire tmux scrollback, bounded by the configured history limit. On success the capture is returned ALONE (`source='mux-full-history'`), superseding the byte buffer so nothing duplicates. Only the FIRST buffer load after a page load requests `full=1`; tab switches keep the cheap `?tail=` path. → [architecture-invariants#full-scrollback-replay](docs/architecture-invariants.md#full-scrollback-replay)
+**Full-scrollback replay**: `GET /api/sessions/:id/terminal?full=1` returns the whole tmux scrollback ALONE (`source='mux-full-history'`), superseding the byte buffer. First load of each non-shell TUI session requests it (`_fullHistoryLoaded`); Shell selection and drop recovery use a bounded 1 MiB `?tail=`, and a Shell scroll-to-top pulls a bounded `?full=1&tail=` window (a window no longer than the browser's buffer is skipped before the downgrade guard, so it never marks the session exhausted); the unbounded pull stays behind **Load full history**. ⚠️ The capture ends with a RELATIVE cursor move back to the pane's caret (never `CUP`), so no line-deleting transform may run over it; those skips key on `isFullCapture`, never on `?full=1` alone. ⚠️ A re-pull must never shrink the buffer (`_replayWouldShrinkBuffer()`). ⚠️ `captureCols`/`captureRows` are absent when no frame was positioned: test `Number.isFinite`, never truthiness. ⚠️ A frame dropped at the 128 KiB render cap MUST be recovered, and the recovery verifies itself: `_scheduleDroppedOutputRecovery` re-arms (bounded by `DROP_RECOVERY_MAX_ATTEMPTS`) while `_onSessionNeedsRefresh` reports no repaint, but never after a capture-fetch `'deadline'`. → [architecture-invariants#full-scrollback-replay](docs/architecture-invariants.md#full-scrollback-replay)
 
-**Self-update** (App Settings → Updates): in-app updater for git-clone installs supervised by systemd/launchd (`systemd`, `launchd`, `launchd-daemon`, else `none` → "restart manually"). The update restarts the very process running it, so the real work runs in a DETACHED `scripts/self-update.sh` that outlives the restart and writes progress to `update-status.json`, which the browser polls across the connection drop. `src/web/self-update.ts` splits pure helpers (unit-tested) from IO wrappers. npm installs report as non-updatable. → [architecture-invariants#self-update](docs/architecture-invariants.md#self-update)
+**Split-pane sessions** (`showSplitButton`, header button, default OFF, desktop-only, per-device): a second live session ("Pane B") beside the active one, in its own `SplitTerminalPane` (terminal-split.js) with its own xterm + WebSocket, resizable via a draggable divider. Deliberately plainer than the primary pane — no local-echo overlay, CJK IME, or touch handlers — and NOT persisted across reloads. → [architecture-invariants#split-pane-sessions](docs/architecture-invariants.md#split-pane-sessions)
+
+**Terminal touch gestures: link taps and text selection**: on touch devices xterm's linkifier and SelectionService never see the gesture, so both are driven explicitly (terminal-ui.js). ⚠️ A tap activates the link under it through the SAME provider as the hover linkifier (`_terminalLinkAtPoint`), synchronously inside `touchend` (keeps the user gesture `window.open` needs) and BEFORE any mouse report; the caret's logical line (`_tapIsOnCaretLine`) and TUI-owned rows (`_isActionableMobileTerminalTap`) keep their meaning. ⚠️ Gate on the caret line, never on tap intent (a shell calls every tap `'input'`). ⚠️ Long-press selects via xterm's public `select()`; keep the three guards: suppress the compat mouse pair after `touchend`, the bounded focus guard + `contextmenu` suppression for the platform long-press, and no closing `terminal.focus()` on phones. Tests: `test/terminal-touch-tap.test.ts`. → [architecture-invariants#terminal-touch-gestures-link-taps-and-text-selection](docs/architecture-invariants.md#terminal-touch-gestures-link-taps-and-text-selection)
+
+**Auto Copy (copy-on-select)** (`autoCopySelection`, per-device, default OFF): a finished terminal selection lands on the clipboard with no keystroke. ⚠️ Copy at the END of a gesture, never in `onSelectionChange` (per-cell); it only arms `_autoCopyPending` and a document-level `mouseup` flushes. ⚠️ The flush must be SYNCHRONOUS in the handler (both clipboard paths need user activation); never defer it to a timer. ⚠️ Touch needs its own calls from `_endTouchSelectionGesture()`/`_selectTouchSelectionLine()` (no mouseup arrives). ⚠️ Unlike `copyTerminalSelection()`, never clear the selection or focus the terminal; restore prior focus. Guards are pure in `decideAutoCopy()` (constants.js, 1M-char cap, refused not truncated). Tests: `test/terminal-auto-copy.test.ts`. → [architecture-invariants#auto-copy-copy-on-select](docs/architecture-invariants.md#auto-copy-copy-on-select)
+
+**Ctrl+V paste trap** (`image-input.js`): `Ctrl+V` routes through `_handleImagePaste()`, which focuses a hidden `contenteditable` trap and reads the clipboard from the paste event landing there; images upload and their paths are typed in, text goes through `terminal.paste()` so bracketed-paste markers survive. ⚠️ **The trap must consume exactly ONE paste event** (Firefox delivers two per keypress: the `execCommand('paste')` event and the keydown's default action); the one-shot flag lives on the trap, never on a browser check. ⚠️ Do not remove the `execCommand('paste')` call: on some mobile engines it is the only route into the trap, and the trap is the only place image blobs are read. Tests: `test/image-paste-trap.test.ts`. → [architecture-invariants#terminal-paste-ctrlv](docs/architecture-invariants.md#terminal-paste-ctrlv)
+
+**Terminal scrollback strip + wheel/touch forwarding**: codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed shell/opencode/antigravity/omp get a NARROW strip (alt-screen toggles only). ⚠️ Gated on `useMux`: direct-PTY sessions must keep the alt screen. Wheel and touch forward to the CLI for **claude ≥ 2.1.187 ONLY, and only while it has mouse tracking on** (`cliMouseTracking`: fullscreen claude sets it, its default inline renderer does not and scrolls locally like codex); ⚠️ never re-add codex without a fresh measurement (it ignores SGR wheel reports). ⚠️ `getClaudeCliVersion()` must never cache a FAILED probe. ⚠️ Hand-report clicks only while the CLI has mouse tracking on: `_shouldReportMouseToCli()` gates all three report sites on `cliMouseTracking` (from `_recordStrippedMouseMode()`, session.ts), or a plain shell prints the reports as literal text. Read `_logScrollRouting()` before diagnosing a scroll report. → [architecture-invariants#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding](docs/architecture-invariants.md#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding)
+**Detached start + service install**: `codeman web -d` relaunches the same entry script `detached:true` (setsid); `nohup` is not what makes it survive. ⚠️ Both `-d` and `service install` must REFUSE when a server is already up on this data dir (pidfile + `/api/status` probe), or a second instance attaches to the first one's live sessions. ⚠️ Never report success not observed: poll `/api/status` until the child answers or dies. `--stop` must verify the pid still looks like Codeman (`ps -o command=`) before signalling. Unit/label names live only in `config/service-names.ts`. `service install` bakes the installing shell's PATH into the unit and never writes `CODEMAN_PASSWORD` into it. → [architecture-invariants#detached-start-and-service-install](docs/architecture-invariants.md#detached-start-and-service-install)
+
+**Self-update** (App Settings → System → Updates): in-app updater for git-clone installs under a supervisor (`systemd`, `launchd`, `launchd-daemon`, `docker-compose`, else `none`). The work runs in a DETACHED `scripts/self-update.sh` writing `update-status.json`, polled across the restart; pure helpers in `src/web/self-update.ts`. ⚠️ Compose: the restart kills the script, so nothing may be appended after the `restarting` marker; the repo must stay a host bind mount over `/opt/codeman` and the image must keep devDependencies + toolchain. ⚠️ `evaluateEnvironmentGate()` refuses releases that change `server.Dockerfile`/`docker-compose.yaml` or add `.env.example` keys, re-evaluated on `POST /api/system/update`; unknowns fail OPEN, but the exit-to-restart needs `--restart-by-exit 1` (`CODEMAN_RESTART_BY_EXIT=1` only in the Compose file). ⚠️ Keep the agent CLIs in `server.Dockerfile` pinned. → [docs/docker-self-update.md](docs/docker-self-update.md), [architecture-invariants#self-update](docs/architecture-invariants.md#self-update)
+
+**Reverse-proxy base path** (`--base-url` / `CODEMAN_BASE_URL`, default `/`; pure single source `src/config/base-path.ts`, normalized to `''` or `/foo`): mounts Codeman under a sub-path behind a proxy that forwards the prefix unchanged. Few choke points: `stripBasePath()` in Fastify's `rewriteUrl` (routes stay prefix-agnostic; unprefixed requests still answer), one `onSend` hook rebasing `Location`, `renderIndexHtml` rewriting `<base href>` + injecting `window.__CODEMAN_BASE__`, and `CodemanBase.url()` (constants.js) for runtime URLs. ⚠️ Keep template asset refs RELATIVE, and route every root-absolute frontend URL (EventSource/WebSocket/`window.open`/src) through `CodemanBase.url()`. ⚠️ Web-tab proxy egress goes through `proxyPrefixFor(cap, basePath)`; ingress parsers stay base-agnostic. ⚠️ `--base-url` must ride `buildWebArgs` and `resolveServicePlan`. Tests: `test/base-path.test.ts`. → [architecture-invariants#reverse-proxy-base-path](docs/architecture-invariants.md#reverse-proxy-base-path)
 
 **Attachments** (live external document references; all wiring in `file-routes.ts`): a **registry** maps a stable `attachmentId` to a realpath-resolved, extension-allowlisted absolute path, so browser requests never carry arbitrary absolute paths. ⚠️ The **magic-link scanner** (`codeman://attach?...` in terminal output) is **prompt-injectable**, so its scan path is force-confined to the session workspace; a hostile prompt could otherwise exfiltrate arbitrary host files over SSE. The security gate is an extension **allowlist**, not a blocklist. `document-conversion-limiter.ts` caps converter spawns globally: without it, N large docs detected at once fork N multi-minute processes, which is a resource-exhaustion vector. → [architecture-invariants#attachments](docs/architecture-invariants.md#attachments)
 
+**File-path links (terminal + chat)**: a path an agent prints is clickable on BOTH surfaces and opens the file-preview overlay. ⚠️ ONE pattern (`FILE_PATH_LINK_PATTERN` / `absoluteFilePathPattern()` in constants.js) feeds the xterm link provider AND `_linkifyFilePaths()`, a fresh instance per call (`lastIndex`). The chat linkifier walks TEXT NODES with DOM APIs, never rebuilds sanitized markup as a string. ⚠️ An out-of-workspace path goes through the ATTACHMENT routes (`POST /api/sessions/:id/attachments` with `notify: false`), never by widening `file-content`/`file-raw` or `file-stream-manager`'s `tail -f` allowlist. ⚠️ `TEXT_ATTACHMENT_EXTENSIONS` IS `EDITABLE_EXTENSIONS` (never a second list), and widening READ must never widen RUN: `html`/`htm`/`svg` stay download-only, other text is inert `text/plain`+`nosniff`. Media extensions are single-sourced in `attachment-registry.ts`. → [architecture-invariants#file-path-links-terminal--response-viewer](docs/architecture-invariants.md#file-path-links-terminal--response-viewer)
+
 **Filesystem path picker** (Link Existing "Browse" + the mobile keyboard's `📁 Path` key): lazy one-directory browsing via `GET /api/filesystem/browse`, with `GET /api/filesystem/preview` for the tapped file. Inserts the path **without** Enter, so the prompt is never submitted; the sibling `⌫ All` key clears only the unsent prompt and must never send the agent's `/clear`. ⚠️ This is a **second file-serving surface and inherits neither the attachment confinement nor its ownership scoping** — it allowlists Home, `CASES_DIR`, `/mnt/d` and `CODEMAN_FILE_PICKER_ROOTS`, blocks sensitive trees, and rejects symlink escapes **after** `realpath`. ⚠️ The optional `sessionId` is an ownership boundary that must be `canAccessOwned`-checked by hand (it does not go through `findSessionOrFail`), and in multi-user mode a non-admin gets only their own `userSpacePath` as a root: per-user spaces live INSIDE `homedir()`, so a `Home` root exposes every other user's workspace. Previews go through the same global conversion limiter, and Markdown/TXT/JSON are served as inert `text/plain`. → [architecture-invariants#filesystem-path-picker](docs/architecture-invariants.md#filesystem-path-picker)
 
+**File Viewer edit mode** (issue #212): the file-preview overlay edits workspace text files in place — `GET .../file-content?edit=1` + `PUT /api/sessions/:id/file-content`, policy in `src/config/file-editing.ts`. This is a **third file surface and the only one that WRITES**: read-path confinement (realpath + workspace + ownership) plus sensitive/blocked/`.git` denies and an extension **allowlist**; writes are `wx`-temp + rename (no `O_CREAT` anywhere = edit-in-place is structural); optimistic concurrency via sha256 `baseHash` → 409. ⚠️ `edit=1` never truncates and the client must never save a plain-preview buffer (the 500-line truncation would silently delete the rest). ⚠️ CRLF/UTF-8 guards: EOL re-applied server-side, non-UTF-8 refused via round-trip compare. → [architecture-invariants#file-viewer-edit-mode](docs/architecture-invariants.md#file-viewer-edit-mode), `docs/file-viewer-edit-plan.md`
+
+**Files panel search** (COD-236, the `q` param on `GET /api/sessions/:id/files`): `compileFileQuery()` (`utils/file-query.ts`, pure) compiles the query into a predicate the server-side walk prunes with; a query returns a FLAT match list and the walk recurses past non-matching directories. An empty, whitespace-only or overlong (`MAX_QUERY_LENGTH`, 256) query compiles to `null`, keeping the default tree response byte-identical. ⚠️ **Never compile a glob into a RegExp** (`*a*a*a…` backtracks and freezes the event loop for the whole server): `globMatch()` is a two-pointer wildcard walk. → [architecture-invariants#files-panel-search](docs/architecture-invariants.md#files-panel-search)
+
+**Raw file bodies are streamed and range-aware**: `file-raw`, the attachments `/raw` route and `GET /api/download` share `sendFileBody()`, advertise `Accept-Ranges: bytes` and answer `Range` with `206` + `Content-Range` (single-range, parser in `src/web/http-range.ts`); without it `<video>` cannot seek. The size cap (`MAX_FILE_DOWNLOAD_BYTES`, default 2GB, env `CODEMAN_MAX_DOWNLOAD_BYTES`, `0` = unlimited) is a sanity bound, not memory protection; never reintroduce a whole-file buffer. ⚠️ Bodies go out via `reply.hijack()`, so `sendRawStream` must copy the status onto `reply.raw` by hand or a partial body ships as `200`. ⚠️ Closing the preview must pause and unload media (`_stopFilePreviewMedia`), since a detached `HTMLMediaElement` keeps playing. → [architecture-invariants#raw-file-bodies-streamed-and-range-aware](docs/architecture-invariants.md#raw-file-bodies-streamed-and-range-aware)
+
 **Ultracode / workflow-run visualization** (opt-in, default OFF): the Workflow tool writes a completion artifact only at run *end*, so live in-flight runs exist solely as transcript dirs. `workflow-run-watcher.ts` therefore synthesizes ACTIVE runs from transcripts until the completion artifact appears and supersedes them. It is **STANDALONE** and deliberately never imports or touches `subagent-watcher.ts`, despite reading the same tree. Two independent toggles: `showUltracodeAgents` (docked panel) and `ultracodeFloatingWindows` (floating windows); the watcher starts if **either** is on. → [architecture-invariants#ultracode--workflow-run-visualization](docs/architecture-invariants.md#ultracode-and-workflow-run-visualization)
 
-**Cross-session search**: `GET /api/search` federates an in-memory search over session metadata, run-summary events, and attachment-history entries. The pure core `searchSources()` does substring matching with hard per-type caps: **no regex (so no ReDoS) and no filesystem reads (so no traversal)**. The server-private `externalPath` is never read. → [architecture-invariants#cross-session-search](docs/architecture-invariants.md#cross-session-search)
+**Clone a repository as a case** (issue #236, Add Case → **Clone Repo**): `POST /api/cases/clone` clones synchronously into the caller's case space (bounded by `GIT_CLONE_TIMEOUT_MS`, no job store); `POST /api/cases/clone-preflight` checks anonymous cloneability and lists refs. Core in `src/git-clone.ts`. ⚠️ **The URL is a code-execution surface**: refuse every `::` form and a leading `-`, spawn only argv arrays with `--` before operands. ⚠️ Stay non-interactive (`gitNonInteractiveEnv()`) or the open request hangs; never collect credentials, refuse `user:password@` URLs. ⚠️ Timeout kills the process GROUP, remove the destination only if this attempt created it, and repo contents win over scaffolding (existing `CLAUDE.md` kept, hooks merged, repo `.claude/settings*` warned about). → [architecture-invariants#clone-a-repository-as-a-case](docs/architecture-invariants.md#clone-a-repository-as-a-case)
 
-**Web tabs** (dashboard URLs as tabs): a saved URL renders as a tab beside agent sessions. **NOT a sixth `SessionMode`** (no PTY, no tmux, no respawn), same reasoning that keeps Docker/remote-SSH as case overlays. Dashboards are **proxied through Codeman's own origin** by default, because a direct iframe fails three ways at once: prod is HTTPS so `http://` targets are blocked as mixed content, many dashboards send `X-Frame-Options: DENY`, and our own `default-src 'self'` CSP blocks cross-origin frames. Proxying leaves the prod CSP unchanged (`/webview/...` is `'self'`). ⚠️ The proxy is **NOT an API surface**: it authenticates on an in-memory capability in the path and is correspondingly exempt from the cookie + Origin checks; that exemption is fenced to safe methods and non-`/api` paths and is pinned by `test/webview-auth-exemption.test.ts`. ⚠️ Iframes omit `allow-same-origin` unless a dashboard is explicitly marked `trusted`, and `Authorization`/`codeman_session` are stripped upstream in **both** modes so `CODEMAN_PASSWORD` cannot leak. ⚠️ A sandboxed frame is **opaque-origin**, which breaks two things `curl` can never reproduce: its runtime-built root-absolute URLs escape `<base>` (fixed by an injected `runtimeUrlShim()`), and its same-host `fetch`/XHR are CORS-checked with `Origin: null` (fixed by `buildProxyCorsHeaders()` plus exempting the proxy from the global `OPTIONS`-204 short-circuit in `registerSecurityHeaders`). Both present as the dashboard's own "Failed to fetch" while the page renders fine. → [architecture-invariants#web-tabs](docs/architecture-invariants.md#web-tabs), `docs/web-tabs.md`
+**Cross-session search**: `GET /api/search` federates an in-memory search over session metadata, run-summary events, and attachment-history entries. The pure core `searchSources()` does substring matching with hard per-type caps: **no regex (so no ReDoS) and no filesystem reads (so no traversal)**. The server-private `externalPath` is never read. PAST sessions (#261) come from `session-history-index.ts`, a capped snapshot of the unified list filled **outside** the request path (`/api/sessions/unified` publishes it; a stale one is rebuilt fire-and-forget), that indirection is what keeps the no-fs property. ⚠️ The snapshot is stored UNSCOPED with a per-row owner and MUST be re-filtered through `canAccessOwned()` on read; history rows carry `jumpTo.kind:'resume-session'`, since a closed session has no tab to select. → [architecture-invariants#cross-session-search](docs/architecture-invariants.md#cross-session-search)
+
+**Web tabs** (dashboard URLs as tabs): a saved URL renders as a tab beside sessions, **NOT a `SessionMode`**, and is proxied through Codeman's own origin (`/webview/<cap>/...`). ⚠️ The proxy is NOT an API surface: its capability-based auth exemption stays fenced to safe methods and non-route paths (`test/webview-auth-exemption.test.ts`). ⚠️ Iframes omit `allow-same-origin` unless `trusted`, and `Authorization`/`codeman_session` are stripped upstream in both modes. ⚠️ **Egress guard**: link-local and cloud-metadata targets are refused at save time, by a sync hostname check at each connect (IP literals skip DNS), AND on the resolved address (`webview-egress.ts`); use the `undici` package's own `fetch` + `Agent`, never Node's global fetch. ⚠️ Loopback links in agent output auto-open as proxied web tabs (`openLinkThroughWebTabIfLoopback`), but never auto-route `*.localhost` (prompt-injectable DNS). Capabilities are revoked on logout (`revokeOwner`). → [architecture-invariants#web-tabs](docs/architecture-invariants.md#web-tabs), `docs/web-tabs.md`
 
 **Multi-user mode** (opt-in `--multiuser` / `CODEMAN_MULTIUSER=1`, OFF by default): named users with scrypt-hashed passwords in `~/.codeman/users.json`. Gated everywhere by `isMultiUserMode()`; when OFF, behavior is byte-identical to single-user because every scoping helper short-circuits. ⚠️ **Not a security boundary at the agent layer**: every session still runs as the SAME OS account. This separates WORKSPACES; it does not sandbox users (Docker cases are the isolation story). Ownership threads through `Session.owner` and is enforced in `findSessionOrFail`, list endpoints, SSE routing (fail-closed), WS, search, and file-preview. → [architecture-invariants#multi-user-mode](docs/architecture-invariants.md#multi-user-mode), `docs/multi-user-plan.md`
 
@@ -230,37 +317,71 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph
 
 ### Frontend
 
-Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `i18n.js`(1.5) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `input-cjk.js`(5.5) → `sanitize-html.js`(5.6) → `app.js`(6) → `terminal-ui.js`(7) → `respawn-ui.js`(8) → `ralph-panel.js`(9) → `orchestrator-panel.js`(9.5) → `cron-ui.js`(9.7) → `settings-ui.js`(10) → `panels-ui.js`(11) → `ultracode-panel.js`(11.5) → `admin-ui.js`(11.7) → `session-ui.js`(12) → `webview-tabs.js`(12.5) → `mobile-overview.js`(12.55) → `entrance-animations.js`(12.6) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15) → `ultracode-windows.js`(15.5) → `image-input.js`(16). `i18n.js` translates static + newly inserted application DOM while skipping terminal/response/file/user-name surfaces; `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData).
+Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order: `constants.js`(1) → `i18n.js`(1.5) → `mobile-handlers.js`(2) → `voice-input.js`(3) → `notification-manager.js`(4) → `keyboard-accessory.js`(5) → `input-cjk.js`(5.5) → `terminal-keycode229-recovery.js`(5.55) → `sanitize-html.js`(5.6) → `app.js`(6) → `tab-rail-resize.js`(6.5) → `terminal-ui.js`(7) → `terminal-split.js`(7.5) → `respawn-ui.js`(8) → `ralph-panel.js`(9) → `orchestrator-panel.js`(9.5) → `cron-ui.js`(9.7) → `settings-ui.js`(10) → `panels-ui.js`(11) → `readmymind-ui.js`(11.3) → `ultracode-panel.js`(11.5) → `approvals-ui.js`(11.6) → `reboot-restore-ui.js`(11.65) → `admin-ui.js`(11.7) → `session-ui.js`(12) → `host-wake-ui.js`(12.2) → `webview-tabs.js`(12.5) → `mobile-overview.js`(12.55) → `home-sessions.js`(12.56) → `entrance-animations.js`(12.6) → `ralph-wizard.js`(13) → `api-client.js`(14) → `subagent-windows.js`(15) → `ultracode-windows.js`(15.5) → `session-lineage.js`(15.6) → `image-input.js`(16). `i18n.js` translates static + newly inserted application DOM while skipping terminal/response/file/user-name surfaces; `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData). `terminal-keycode229-recovery.js` forwards a committed `input` event that xterm's `_inputEvent` guard drops (Chrome-on-Android soft keyboards send `composed: true` after a keydown), and only when xterm emitted no canonical data for that keystroke. ⚠️ **That decision is settled at the NEXT keydown as well as on its own zero-delay timer** (#441): the drain runs from xterm's custom key handler, which fires BEFORE xterm processes that key, so a soft keyboard that commits the last character and sends Enter in one InputConnection transaction puts the character on the wire ahead of the `\r`. On the timer alone that character is not merely late, it is LOST: xterm emits the `\r` first and bumps the canonical counter past the candidate's snapshot, so the candidate stands down (measured, `hell\r` where the user typed `hello`). The trade is that a keydown decides with less evidence than the timer did, since xterm's own keyCode-229 rescue has not run yet; that is safe for Enter, which clears the textarea so the pending diff emits nothing. Ordering is pinned by `test/terminal-keycode229-recovery.browser.test.ts`, which the CI gate does NOT run.
 
-**Entrance animations** (`entrance-animations.js`, all OFF by default): opt-in animations for the four things that appear when work starts, chosen per surface via `data-tab-anim` / `data-term-anim` / `data-win-anim` / `data-line-anim` on `<html>`. Defaults are the `legacy` theme, so an untouched install behaves exactly as before and every hook short-circuits on its first line. ⚠️ Tabs and connection lines are **destroyed mid-animation** on every re-render (`_fullRenderSessionTabs()` replaces the strip's innerHTML; `_updateConnectionLinesImmediate()` does `svg.innerHTML = ''`), so both are tracked by id and re-applied to the fresh element with a **negative `animation-delay`** to resume rather than restart. ⚠️ The terminal-pane styles may animate **transform / opacity / clip-path only**, xterm's FitAddon derives rows+cols from `getComputedStyle(parent).width/height`, so animating width/height/padding there would resize the PTY. ⚠️ Window styles other than `beam` transform the window, which moves the rect its connection line is aimed at; `beam` deliberately animates opacity/filter only so its line can draw toward a stable target. Persisted to its own `codeman:*Anim` localStorage keys (per-device, deliberately NOT in the `.strict()` `SettingsUpdateSchema`); picker in App Settings → Appearance, full per-surface lab at `?animlab=1`.
+**Entrance animations** (`entrance-animations.js`, all OFF by default): opt-in animations for tabs, terminal, windows and connection lines, chosen via `data-tab-anim` / `data-term-anim` / `data-win-anim` / `data-line-anim` on `<html>`; the default `legacy` theme short-circuits every hook. ⚠️ Tabs and lines are destroyed mid-animation on re-render, so re-apply to the fresh element by id with a negative `animation-delay` (resume, never restart). ⚠️ Terminal-pane styles may animate only transform / opacity / clip-path (anything else resizes the PTY via FitAddon); `blur` is the ONE sanctioned `filter` exception, do not generalise it. ⚠️ Line glow lives in `--line-glow` so blur keyframes interpolate. Persisted per-device in `codeman:*Anim` localStorage keys, never in `SettingsUpdateSchema`; lab at `?animlab=1`. Test: `test/entrance-animations.test.ts`. → [architecture-invariants#entrance-animations](docs/architecture-invariants.md#entrance-animations)
 
-**Phone overview home screen** (`mobile-overview.js`, phones only, per-device `mobileOverviewEnabled`, default ON): under 430px the "C" logo shows a session overview (NEEDS YOU / CURRENT SESSIONS / PAST SESSIONS) instead of the welcome overlay; tablet and desktop are unchanged. The branch lives in `showWelcome()`/`hideWelcome()` (terminal-ui.js) behind `shouldUseMobileOverview()`, which is **width-driven** (`getDeviceType() === 'mobile'`) because this is a layout decision, unlike the settings namespace which stays handheld-based. ⚠️ The container ships with the `hidden` attribute and only this module removes it: never give `.mobile-overview` a bare `display` rule, since desktop does not load `mobile.css` (`media="(max-width: 1023px)"`) and would then render it unstyled. Live re-renders ride on the tail of `_renderSessionTabsImmediate()` (every state change it needs already funnels there); PAST rows come from one `_fetchUnifiedSessions(60)` per home-screen visit and resume through the shared `resumeHistorySession()`, so they behave exactly like the welcome screen's Resume list. ⚠️ Two things must stay in lockstep with surfaces outside this module, because divergence reads as a bug rather than a style: the split Run button carries the **toolbar's own classes** (`btn-toolbar btn-run mode-<backend>` / `btn-run-gear`) so the per-backend gradient and the light-skin overrides apply unchanged (mobile.css must therefore set no `background`/`color` on it), and row status uses the **session-tab language** (green dot when fine, `pulse` while working, yellow blinking row when waiting for input, red blinking row when a question is pending, mirroring `tab-alert-idle`/`tab-alert-action`). The picker mirrors the toolbar run-mode menu (`setRunMode()` + `run()`, `openWebviewFromMenu()` for saved dashboards) and deliberately omits its Recent-Sessions block, since PAST SESSIONS is that. Status pills carry `data-i18n-skip` (generic words like "idle" collide with state strings elsewhere).
+**Mobile tab strip scrolling** (issue #257): under 768px the tab strip scrolls horizontally, so the active tab must be kept reachable. `_updateActiveTabImmediate()` reveals it via `computeTabScrollLeft()` (constants.js, rect math on the strip's own `scrollLeft`, never `scrollIntoView()`, which scrolls the document under the fixed header); `_fullRenderSessionTabs()` must restore `scrollLeft` across rebuilds and re-reveal only when the active tab changed (`_lastRenderedActiveTabId`). ⚠️ The phone-block `min-width` on `.session-tab.active .tab-name` keeps the tab's centre off the gear/close icons, sized for numberless tabs 10+ (floor 40px); do not shrink it. ⚠️ Never reintroduce hoisting the active session to the front of the strip. Test: `test/mobile-tab-tap-zones.test.ts`. → [architecture-invariants#mobile-tab-strip-scrolling](docs/architecture-invariants.md#mobile-tab-strip-scrolling)
 
-**Command palette + shortcut registry**: `Ctrl/Cmd/Alt+K` opens the session palette; shortcuts live in a rebindable registry (`DEFAULT_SHORTCUTS`/`getShortcutRegistry()`/`matchesShortcutEvent()` in app.js, overrides in `settings.shortcutOverrides`). ⚠️ Palette-chord keys must ALSO be swallowed in `attachCustomKeyEventHandler` (terminal-ui.js) or xterm writes the control byte (0x0B) into the PTY. ⚠️ `saveAppSettings()` rebuilds settings from the DOM, so keys edited elsewhere (`shortcutOverrides`, `showTokenCount`, `showCost`) need explicit `_prev` carry-over. → [architecture-invariants#command-palette-and-shortcut-registry](docs/architecture-invariants.md#command-palette-and-shortcut-registry)
+**Session list layout: header strip or left sidebar** (`sessionListLayout`, default `header`; per-device via `displayKeys`, also in `SettingsUpdateSchema`): the list can move into a collapsible `<aside>` (Alt+B, `toggleSessionSidebar`) or, via `tabOrientation`, a resizable vertical `#tabRail` (desktop/tablet only). ⚠️ There is ONE `#sessionTabs`, MOVED between hosts, never a second list: `applySessionListLayout()` runs first, then `applyTabOrientation()`, both BEFORE `applyTabWrapSettings()`, and both arm/disarm `_startSidebarRichClock()`. ⚠️ Axis decisions use `_isVerticalTabList()`, never `isSessionSidebarActive()` alone. ⚠️ Rich rows share one gate, `isRichTabRows()`; rich CSS pairs sidebar+rail with comma-grouped selectors, never `:is()`, and card rules stay rail-scoped. ⚠️ Rail sort (`tabRailSort`, default `activity`) is the flex `order` property only, never a DOM reorder; the arrow-key walk alone follows computed `order`. ⚠️ Leaving sidebar mode clears `_sidebarFilter`; the handheld overlay drawer is `inert` when closed, the docked rail never. → [architecture-invariants#session-list-layout-header-strip-vs-left-sidebar](docs/architecture-invariants.md#session-list-layout-header-strip-vs-left-sidebar)
+
+**Phone overview home screen** (`mobile-overview.js`, per-device `mobileOverviewEnabled`, default ON): under 600px the "C" logo shows NEEDS YOU / CURRENT / PAST SESSIONS instead of the welcome overlay, branched in `showWelcome()`/`hideWelcome()` via width-driven `shouldUseMobileOverview()`. ⚠️ The container ships `hidden` and only this module removes it: never give `.mobile-overview` a bare `display` rule (desktop does not load `mobile.css`). ⚠️ The split Run button must carry the toolbar's own classes (`btn-toolbar btn-run mode-<backend>` / `btn-run-gear`) and mobile.css must set no `background`/`color` on it; row status must mirror the session-tab alert language. PAST rows resume through the shared `resumeHistorySession()`. Status pills carry `data-i18n-skip`. → [architecture-invariants#phone-overview-home-screen](docs/architecture-invariants.md#phone-overview-home-screen)
+
+**Desktop home tab rail** (`home-sessions.js`, desktop only): the welcome overlay's left gutter carries the open tabs as a rail docked flush left, full height, in overview order, each row showing `created … · <state> <duration>` from `_mobileOverviewSince()`; state classification is reused from mobile-overview.js (so it loads after it). ⚠️ The number badge is the Alt+1..9 tab-strip index, never renumber it to row position. ⚠️ The width gate lives in two places that must stay equal: `HOME_SESSIONS_MIN_WIDTH` (1180) and a `max-width: 1179px` media query. ⚠️ `.home-sessions[hidden]` must re-assert `display: none`. ⚠️ Size all children in `em` off the one `clamp()` knob, never `rem`/px. Age stamps tick in place (`_tickHomeSessionsTimes()`), never by re-render. Test: `test/home-sessions.test.ts`. → [architecture-invariants#desktop-home-tab-rail](docs/architecture-invariants.md#desktop-home-tab-rail)
+
+**Home-screen session order** (`CodemanSessionOrder` in constants.js, pure): BOTH home screens (phone overview, desktop rail) must order rows through this ONE comparator. Rank `needs` → `error` → `waiting` → `working` → `idle` → `done`. ⚠️ The tiebreak flips: states a session is still IN sort oldest-first, states it has STOPPED sort newest-first. ⚠️ The running group keys off `lastSubmitAt`, never `lastActivityAt` (a working pane repaints constantly). ⚠️ A 0 stamp means unknown and sorts last within its state. Final tiebreak is `orderIndex`, so the list never shuffles. The tab strip itself is NOT sorted by this. Test: `test/session-overview-order.test.ts`. → [architecture-invariants#home-screen-session-order](docs/architecture-invariants.md#home-screen-session-order)
+
+**Welcome "Resume Conversation" list** (terminal-ui.js): `loadHistorySessions()` fetches once and caches the corpus on `_historyAll`/`_historyCases`; every subsequent view (filter box, sort select, expand, the periodic refresh in panels-ui.js) goes through `_renderHistoryList()`, so never append rows to `#historyList` directly or re-fetch to re-sort. ⚠️ The box height is **class-driven**: expanding the list without `.history-list.expanded` leaves the collapsed `max-height` in place and just deepens a scroll well, which is the bug #260 reported (35 sessions in a ~4-row box). ⚠️ The A–Z sort keys off `_historyRowLabel()`, the SAME string the row renders (`name || firstPrompt || path`), most rows are transcript-backed and have no session name, so sorting on `name` alone silently does nothing. ⚠️ A filter implies expansion, and `_renderSearch()` hides `#historyHeader` (title + controls) as one unit while a search is active. Tests: `test/history-list-controls.test.ts`.
+
+**Command palette + shortcut registry**: `Ctrl/Cmd/Alt+K` opens the session palette; shortcuts live in a rebindable registry (`DEFAULT_SHORTCUTS`/`getShortcutRegistry()`/`matchesShortcutEvent()` in app.js, overrides in `settings.shortcutOverrides`). ⚠️ Palette-chord keys must ALSO be swallowed in `attachCustomKeyEventHandler` (terminal-ui.js) or xterm writes the control byte into the PTY. ⚠️ `saveAppSettings()` rebuilds settings from the DOM, so keys edited elsewhere (`shortcutOverrides`, `showTokenCount`, `showCost`) need explicit `_prev` carry-over. ⚠️ **Smart copy (`Ctrl+C`)**: with no selection it must `return true` without `preventDefault()` or the interrupt is lost; keep `copyTerminalSelection` out of `SHORTCUT_ACTIONS`. The gate tests the CLEANED selection (`CodemanCopySelection.clean`: trailing padding, plus a LEADING margin only up to the width the CLI declares in `capabilities.transcriptGutter`, never one derived from the pane); the strip is not idempotent, so clean once and pass the RAW selection on, and leave Alt+drag column selections untouched. → [architecture-invariants#command-palette-and-shortcut-registry](docs/architecture-invariants.md#command-palette-and-shortcut-registry)
 
 **Per-device vs synced settings**: the `displayKeys` set in settings-ui.js is a **client-side merge policy**, not a wire filter. A display key seeds from the server only when localStorage has no value for it, which is what prevents one device overwriting another; `showPlanUsageLimits` is additionally `delete`d from the incoming payload outright. Separately, `SettingsUpdateSchema` is `.strict()` and simply **does not declare** `skin`, `showFileViewerButton`, `showCronButton`, `webglRendererEnabled`, `localEchoEnabled`, `cjkInputEnabled`, or `extendedKeyboardBar`, so sending one of those is a validation error. The rest (`showResponseViewer`, `showPlanUsageLimits`, `language`, and most `show*` keys) ARE in the schema and do persist server-side; they are per-device by client policy only. ⚠️ Adding a new per-device setting means deciding **both** questions: membership in `displayKeys`, and presence in the schema.
 
+**Settings surface** (`#appSettingsModal` + `#sessionOptionsModal` + `#createCaseModal`): one `set-*` language shared through a single `:is(...)` id scope in styles.css. App Settings' rail is a table of contents over ONE scrolling document (`switchSettingsTab` scrolls); Session Options and Add Case really switch (`switchOptionsTab` / `switchCaseModalTab`), and their larger per-modal size blocks are the design, not drift. ⚠️ **The load/save contract is `getElementById` by id**: renaming or dropping a control id silently stops it loading or saving. ⚠️ The Session Options "Session" entry still keys off `context` (label-only rename). ⚠️ Add Case keeps its legacy `.form-row` markup via an adapter; every `<details>` there needs `.set-adv-chev` plus both marker suppressions. ⚠️ Model cards and the effort segment are views over hidden `<select>`s, which stay the source of truth. ⚠️ `.modal-tabs*` classes are retired; `admin-ui.js` needs `.set-rail-items` + `.set-doc` to survive any restructure. Guard: `test/app-settings-structure.test.ts`. → [architecture-invariants#settings-surface-app-settings-session-options-add-case](docs/architecture-invariants.md#settings-surface-app-settings-session-options-add-case)
+
 **Header button visibility**: most header controls are opt-in and hidden by a marker class (`btn-multimonitor--hidden`, `btn-response-viewer-header--hidden`, `btn-file-viewer--hidden`, `btn-cron--hidden`) that `applyHeaderVisibilitySettings()` (settings-ui.js) toggles after settings load; the multi-monitor button is instead stripped at render by `renderIndexHtml`. ⚠️ Hiding must go through the marker class: the base rules are `display:inline-flex !important`, so an inline style cannot override them. Current desktop default is WS/CPU/MEM + File Viewer + gear, with the token chip and lifecycle-log button OFF. ⚠️ New header controls must not leak onto phones; `test/mobile-header-buttons-policy.test.ts` is the static guard. → [architecture-invariants#header-button-visibility-multi-monitor-response-viewer-file-viewer-cron](docs/architecture-invariants.md#header-button-visibility-multi-monitor-response-viewer-file-viewer-cron)
 
 **Gesture control** (camera hand-tracking overlay, opt-in, default OFF): `CODEMAN_GESTURE=1` makes the feature *available*; `gestureControlEnabled` turns it on. The bundle is injected by `renderIndexHtml` only when enabled, which is why that method is `async` and reads settings with `readSettings(true)` (a fresh read: a post-save reload lands inside the 2s cache TTL and would otherwise render the pre-toggle state). **Source lives in `packages/gesture-control/`; edit there, run `npm run build:gesture`, and commit the regenerated bundle** because dev serves the committed bundle with no runtime bundler. The MediaPipe wasm + model are fetched separately and gitignored. ⚠️ Keep `MP_VERSION` in `fetch-gesture-assets.mjs` in sync with `@mediapipe/tasks-vision`. → [architecture-invariants#gesture-control-the-source-package](docs/architecture-invariants.md#gesture-control-the-source-package)
 
+**Terminal font weight** (`terminalFontWeight` / `terminalFontWeightBold`, per-device, default = xterm's own `normal`/`bold`): Claude Code's markdown bold is a bare `ESC[1m`, so the weight step is its only cue. `CodemanTerminalFont.resolveWeights()` (constants.js, pure) resolves each slot against **its own** xterm default. ⚠️ The `@font-face` for `fonts/jetbrains-mono-variable.woff2` must stay declared `100 800` (the browser synthesizes from the descriptor, not the file); narrowing it silently makes the setting a no-op. ⚠️ A live save must reach both echo overlays (`refreshFont()`) and open Agent Teams panes. ⚠️ Leave `_awaitTerminalFont()` untouched. Test: `test/terminal-font-weight.test.ts`. → [architecture-invariants#terminal-font-weight](docs/architecture-invariants.md#terminal-font-weight)
+
 **Theme skins / branding / i18n**: `skin` selects a palette via `data-skin` on `<html>`, applied by an **inline pre-paint script** in `index.html` reading `localStorage['codeman:skin']` to avoid a flash of wrong theme. ⚠️ A skin is **four things that must stay in sync**, and missing any one degrades silently: the `html[data-skin="…"]` token block in `styles.css`, the xterm ANSI palette in `terminal-ui.js`, the pre-paint allowlist, and the Settings picker (both in `index.html`). `test/skin-themes.test.ts` is the static guard. Light skins additionally need `color-scheme: light` and xterm `minimumContrastRatio: 4.5`, and `applyTerminalSkin()` must call the local-echo overlay's `refreshFont()` because it caches the terminal fg/bg. `displayName` changes user-facing browser branding only and must NEVER rename npm package, CLI, API, storage, CSS, or protocol identifiers. `language` (`en`/`zh-CN`) keeps English as the canonical source so live switching stays reversible. User display names flow through `textContent`/attribute APIs and the server title's HTML escaper, never `innerHTML`. → [architecture-invariants#theme-skins](docs/architecture-invariants.md#theme-skins)
 
 **Foldable settings identity**: responsive layout is width-driven via `MobileDetection.getDeviceType()`, but the localStorage namespace uses `MobileDetection.isHandheldDevice()` so an unfolded Android foldable keeps `codeman-app-settings-mobile`. ⚠️ Do not switch per-device settings namespaces from instantaneous viewport width: a posture-triggered WebView reload would lose opt-in UI. Regression profile: `OPPO Find N5 (unfolded)` in `test/mobile/devices.ts`. → [architecture-invariants#foldable-settings-identity](docs/architecture-invariants.md#foldable-settings-identity)
 
+**Folding devices: a fold is not a keyboard, and dialogs avoid the hinge**: ⚠️ in `handleViewportResize()`, a visual-viewport resize that changes the WIDTH is a shape change (rotation, fold) and must never be read as the keyboard; it re-baselines instead, or `keyboardVisible` latches with no keyboard. ⚠️ `init()` must seed `lastViewportWidth`. ⚠️ With the keyboard up, a shape change baselines to `window.innerHeight`, never the shrunk visual height. ⚠️ The hinge is reserved via `--fold-inline-end`/`--fold-block-end` (0px when unfolded): each overlay fold rule must re-state its own gutter, a base gutter overridden by a later `@media` block needs its own fold restatement there on a zero base, and dialogs use physical sides (left/top segment) in every language. Guard: `test/foldable-layout.test.ts`. → [architecture-invariants#folding-devices](docs/architecture-invariants.md#folding-devices)
+
 **WebGL renderer toggle** (`webglRendererEnabled`, per-device): the GPU-stall watchdog's sticky `codeman-webgl-disabled` marker survives page loads and is cleared only by an explicit OFF→ON save or `?webgl=force`. `?nowebgl` forces the DOM renderer per-load. → [architecture-invariants#webgl-renderer-toggle](docs/architecture-invariants.md#webgl-renderer-toggle)
 
-**Phone toolbar: Enter replaces Shell** (post-1.8.0): inside `@media (max-width: 430px)` `btn-shell` is `display:none` and `btn-enter` takes its slot (`order: 4`); starting a shell moved into the Run dropdown (`Terminal / Shell` → `setRunMode('shell')` → `run()` → `runShell()`, button label "Run SH"). `runMode` is `z.string().max(20)` server-side, so new modes need no schema change. Desktop and tablet keep the green Run Shell button unchanged.
+**Shell keyboard accessory bar + one-shot Ctrl** (`keyboard-accessory.js`): a shell-mode session swaps the mobile accessory bar for terminal controls; `setMode()` records `extendedKeyboardBar` as the base layout and `refreshForActiveSession()` resolves base-vs-shell. ⚠️ Ctrl is a one-shot modifier applied in `terminal.onData` (after `shouldSuppressTerminalQueryResponse`, before every send path), and must skip `isTerminalFocusOrMouseReport()` chunks. ⚠️ It must disarm on use, second tap, any other accessory key, session switch, keyboard dismissal and layout swap. ⚠️ `_handleCjkInput()` must apply it too (the CJK textarea bypasses onData). Mapping: `ctrlByteFor()`. ⚠️ mobile.css's light-skin repaint must keep excluding `.accessory-btn:not(.armed)` or the armed state is invisible. → [architecture-invariants#shell-keyboard-accessory-bar-and-one-shot-ctrl](docs/architecture-invariants.md#shell-keyboard-accessory-bar-and-one-shot-ctrl)
+
+**Mobile prompt composer** (`keyboard-accessory.js`): the agent bars' Paste key is **Compose**, a native multiline dialog where only **Send** submits (the shell bar keeps plain Paste). Opening it adopts the whole terminal prompt (`_takePendingLocalEcho`), erasing the flushed prefix with backspaces counted in code points. ⚠️ Drafts are per-session and in memory only (`_composerDrafts`), never persisted (prompts carry secrets). ⚠️ Delivery is a hand-built bracketed-paste frame via `_sendInputAsync` WITHOUT `useMux`, then a separate delayed Enter WITH it; never `terminal.paste()`, and the frame must never take the mux fallback (it strips newlines). ⚠️ `_composerMaxLength` must stay derived from `MAX_INPUT_LENGTH` minus the markers, or an oversized frame wedges the durable queue. ⚠️ The composer overlay needs its own gutter restatement after the fold rules. Test: `test/mobile-prompt-composer.test.ts`. → [architecture-invariants#mobile-prompt-composer](docs/architecture-invariants.md#mobile-prompt-composer)
+
+**PTY and browser terminal geometry** (#464): a browser terminal whose width differs from the PTY's garbles Claude's redraws, so `syncTerminalGeometry()` (terminal-ui.js) is the ONE function that may resize the main terminal (never a bare `fitAddon.fit()`), a font change is a geometry change, and the fit is withheld wherever the SIGWINCH is. ⚠️ Resize is answered with `Session.ptyGeometry`, and a client adopts its COLUMNS only (never rows); `ptyGeometry` is null without a live pane. → [architecture-invariants#pty-and-browser-terminal-geometry](docs/architecture-invariants.md#pty-and-browser-terminal-geometry)
+
+**Terminal resilience**: a replay clear is the queued in-stream `\x1bc` in `_resetTerminalForReplay()`, never `reset()`/`clear()` (queued bytes fuse into the snapshot); the renderer watchdog `_kickRenderer()` reads xterm privates, pinned by `test/xterm-private-api.test.ts` against the resolved lockfile version; every terminal capture fetch has a deadline that covers the BODY (`_fetchTerminalCapture`). → [architecture-invariants#terminal-resilience-replay-clears-renderer-liveness-fetch-deadlines](docs/architecture-invariants.md#terminal-resilience-replay-clears-renderer-liveness-fetch-deadlines)
+
+**WebSocket output-gap reconcile** (`_wsOutputGapSession`, app.js): output frames carry no sequence number, so an unintentional WS close while SSE stays up marks the session and the next open reconciles. ⚠️ The marker is cleared only once a repaint actually happened (`_markTerminalBufferReconciled()`, never in a `finally`). → [architecture-invariants#websocket-output-gap-reconcile](docs/architecture-invariants.md#websocket-output-gap-reconcile)
+
+**Service worker precache** (`sw.js` + `scripts/build.mjs`): `BUILD_ID` and `HASHED_ASSETS` are build-generated and the build THROWS unless each declaration appears exactly once; `caches.match` must pass `ignoreSearch: true` because `cacheBustAssets` appends `?v=` to hashed names. → [architecture-invariants#service-worker-precache-and-cache-key](docs/architecture-invariants.md#service-worker-precache-and-cache-key)
+
+**Dismissing the on-screen keyboard** (`terminal-ui.js`): two gestures blur the terminal's hidden textarea. (1) `_installMobileKeyboardDismiss()`, a document `touchend` that must never fire inside `#terminalContainer` or on a control (`MOBILE_KEYBOARD_DISMISS_EXEMPT_SELECTOR`, via `closest()`). (2) In `_handleMobileTerminalTap`, a second tap on inert `content` blurs; the prompt row keeps focus-then-position. ⚠️ A scroll also ends in `touchend`: both classifiers must share one threshold (`TAP_THRESHOLD` reads `MOBILE_KEYBOARD_DISMISS_TAP_SLOP`), and multi-touch is never a tap. ⚠️ CI cannot see the only test for (1): run `npm run test:mobile -- test/mobile/keyboard.test.ts` by hand and diff the FAIL list against master. → [architecture-invariants#dismissing-the-on-screen-keyboard](docs/architecture-invariants.md#dismissing-the-on-screen-keyboard)
+
+**Phone toolbar: Enter replaces Shell** (post-1.8.0): inside `@media (max-width: 599px)` `btn-shell` is `display:none` and `btn-enter` takes its slot (`order: 4`); starting a shell moved into the Run dropdown (`Terminal / Shell` → `setRunMode('shell')` → `run()` → `runShell()`, button label "Run SH"). `runMode` is `z.string().max(20)` server-side, so new modes need no schema change. Desktop and tablet keep the green Run Shell button unchanged.
 
 ⚠️ **`sendEnterKey()` MUST go through `terminal._core.coreService.triggerDataEvent('\r', true)`** — not `sendInput()`, and never a raw POST to `/api/sessions/:id/input`. `localEchoEnabled` defaults to `MobileDetection.isTouchDevice()`, so on every phone the characters you type are buffered in the `LocalEchoOverlay` and have **never reached the PTY**; the `onData` Enter branch in terminal-ui.js is what flushes `pendingText` first and only then sends `\r` (after an 80ms delay so text lands first). Sending a bare `\r` submits an empty line and strands the typed text on screen, so the button looks dead. Replaying the keypress reuses the overlay flush, the flushed-offset cleanup and the ordering instead of reimplementing them. `KeyboardAccessory.sendKey()` is for escape sequences (arrows/Esc) and is the WRONG template to copy for input.
 
 ⚠️ **Skin overrides outrank plain class rules.** `styles.css` nests its skin block inside `html:not([data-skin="og"]) { … }`, so a bare `.btn-toolbar` rule in there resolves to specificity **(0,2,1)** and beats a `.btn-toolbar.btn-x` rule **(0,2,0)** in `mobile.css` regardless of load order. Toolbar-button colors set from mobile.css therefore need `!important` — that is why mobile.css leans on it so heavily. Symptom: only your `!important` properties land and everything else silently renders in generic toolbar grey.
 
-**Z-index layers**: subagent windows (1000), plan agents (1100), mobile/tablet fixed header (1200, `mobile.css`), modals on ≤768px (1300 — must beat the fixed header or the modal close button is buried), log viewers (2000), image popups (3000), local echo overlay (7).
+**Connection-loss UI** (`computeConnectionLossUi()` in constants.js, writer `_updateConnectionLossUi()` in app.js): the service worker serves the cached app shell, so an unreachable server (phone off the tailnet, VPN down, server stopped) used to render a normal-looking empty dashboard whose only tell was the 8px header dot, which reads as "no sessions", not "no connection". Two surfaces now: a full-screen **overlay** while no server state has loaded this page load (nothing behind it is worth preserving), and a non-blocking **banner** once it has (the terminal scrollback stays readable). ⚠️ A **2.5s grace** is load-bearing: a COM deploy restarts the server and SSE is back in ~200ms, and a banner on every deploy trains the user to ignore it. `navigator.onLine === false` skips the grace, since that is never a blip. Retry re-arms SSE **and** the terminal WS (`planWsReconnect` can 'give-up', and the SSE backoff caps at 30s).
+
+**SSE staleness watchdog** (`computeSseStale()` in constants.js, `_checkSseStale()` + a 5s interval in app.js): an `EventSource` can stop delivering without erroring, so the client forces a reconnect when nothing arrives. ⚠️ The server keepalive must stay the named `sse:heartbeat` event (`cleanupDeadClients()`, sse-stream-manager.ts), never an SSE comment, which `EventSource` cannot observe; its no-op client listener must stay registered. ⚠️ Judge staleness only while `connected` and online (the loop breaker). ⚠️ The liveness stamp lives inside `addListener`. ⚠️ Clear the interval only at the top of `connectSSE()`, or intervals stack. → [architecture-invariants#sse-staleness-watchdog](docs/architecture-invariants.md#sse-staleness-watchdog)
+
+**Z-index layers** (keep new overlays consistent with this stack): local echo overlay (7), terminal touch-selection bar (900, below floating agent windows), subagent windows + split picker menu (1000), plan agents (1100), mobile/tablet fixed header (1200), modals on ≤768px (1300, must beat the fixed header), log viewers (2000), connection-loss overlay (2500), image popups (3000), response viewer (5000, backdrop 4999), file-preview overlay (5100, must outrank the response viewer that launches it), toasts/path picker (10000+), custom-model center-status banner (10001; its `[hidden]` must re-assert `display: none` or `dismiss()` leaves an invisible click-blocker), custom-model swap-confirm/context-warning modals (10010). → [architecture-invariants#z-index-layers](docs/architecture-invariants.md#z-index-layers)
 
 **Respawn presets**: `solo-work` (3s/60min), `subagent-workflow` (45s/240min), `team-lead` (90s/480min), `ralph-todo` (8s/480min), `overnight-autonomous` (10s/480min).
 
-**Keyboard shortcuts**: Escape (close), Ctrl+? (shortcut overlay), Ctrl/Cmd/Alt+K (session palette), Ctrl+W (kill), Ctrl+Tab (next), Alt+[/] (prev/next tab), Alt+1-9 (switch tab), Ctrl+Shift+{/} (move tab left/right), Shift+Enter or Ctrl+Enter (newline), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl+Shift+V (voice input), Ctrl/Cmd +/- (font), Shift+Wheel (local scrollback when mouse passthrough is active). Rebindable via the registry.
+**Keyboard shortcuts**: Escape (close), Ctrl+? (shortcut overlay), Ctrl/Cmd/Alt+K (session palette), Ctrl+W (kill), Ctrl+Tab (next), Alt+[/] (prev/next tab), Alt+1-9 (switch tab), Ctrl+Shift+{/} (move tab left/right), Shift+Enter or Ctrl+Enter (newline), Ctrl+C (copy selection, else interrupt) / Ctrl+Shift+C (copy, never interrupts), Ctrl+L (clear), Ctrl+Shift+R (restore size), Ctrl+Shift+V (voice input), Ctrl/Cmd +/- (font), Shift+Wheel (local scrollback when mouse passthrough is active), Shift+drag (start a selection in a stripped-DECSET pane, where xterm's own Shift branch is unreachable and a Shift+drag used to select nothing; `_installShiftDragSelection`), right-click (copy the selection, the mintty/PuTTY convention, since xterm paints into a canvas and the native menu has no Copy for it; with nothing selected the native menu is left alone). Rebindable via the registry.
 
 ### Security
 
@@ -276,19 +397,20 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 | **Sessions**      | 24h cookie (`codeman_session`), auto-extend, device context audit                                                                                                                                           |
 | **Rate limit**    | 10 failed auth/IP → 429 (15min decay). QR and hook-secret have separate buckets, so neither can lock out login                                                                                              |
 | **Hook bypass**   | `/api/hook-event` + `/api/status-telemetry` skip Basic auth (localhost-only, schema-validated), but when auth is active the loopback bypass requires `X-Codeman-Hook-Secret` **unconditionally** (Codeman cannot detect a user's own loopback reverse proxy) |
+| **Lost-frame page** | The THIRD unauthenticated 200, beside the two hook routes, and the only one decided by request headers alone: a `GET`/`HEAD` carrying `Sec-Fetch-Dest: iframe\|frame`, `Accept: text/html` and mode `navigate` (or none), for a path that is NOT a registered route (never `/api/`, `/ws/`, `/q/`), is answered BEFORE the credential checks with the static web-tab recovery page (`lostWebviewFramePage`: no reflected input, `default-src 'none'` plus its own script hash, `no-store`). `/` is the one registered route also admitted, only when the request carries neither `codeman_session` nor `Authorization` (nothing in Codeman frames its own root; a sandboxed frame has neither), since the landing page masks to exactly `/` and its reload otherwise rendered Codeman inside the web tab. ⚠️ A non-browser client can set those headers, so an unauthenticated caller can tell a registered route (401) from a non-route (200) and enumerate the route table; accepted, the routes are public in `docs/api-reference.md`. Pinned by `test/webview-auth-exemption.test.ts` + `test/webview-lost-root-frame.test.ts` |
 | **Tunnel**        | Enabling a tunnel **refuses** without `CODEMAN_PASSWORD` unless exposure is acknowledged via `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` or the per-request `acknowledgeUnauthTunnel:true` action field (never persisted) |
-| **Validation**    | Zod schemas, Unicode-aware path allowlist regex, env prefix allowlist (`CLAUDE_CODE_*`/`OPENCODE_*`/`CODEX_*`/`GEMINI_*`/`GOOGLE_*`/`ANTIGRAVITY_*`)                                                        |
+| **Validation**    | Zod schemas, Unicode-aware path allowlist regex, env prefix allowlist (`CLAUDE_CODE_*`/`OPENCODE_*`/`CODEX_*`/`GEMINI_*`/`GOOGLE_*`/`ANTIGRAVITY_*`/`PI_*`/`GROK_*`/`XAI_*`/`DSH_*`/`DEEPSEEK_*`)                                                        |
 | **Headers**       | CORS localhost-only, CSP, X-Frame-Options, HSTS if HTTPS                                                                                                                                                     |
 
 **Security-relevant env vars**: `CODEMAN_MUX` (managed session), `CODEMAN_API_URL` (auto-set for hooks), `CODEMAN_ALLOWED_HOSTS` (extra Host/Origin allowlist entries for reverse proxies; bare `.suffix` matches subdomains), `CODEMAN_DOCKER_BRIDGE_HOOKS=1` (opt-in hooks-only listener on the docker bridge gateway).
 
 ### SSE Event Registry
 
-149 event constants in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). **Both must be kept in sync** — they are currently exactly in sync, and the backend file's `@fileoverview` carries the per-category breakdown.
+Event constants live in `src/web/sse-events.ts` (backend) and `SSE_EVENTS` in `constants.js` (frontend). **Both must be kept in sync**; `test/sse-registry-parity.test.ts` pins it. ⚠️ `hook:agent_working` is the one hook event with no Claude Code hook behind it — the DeepSeek status bridge reports it (see External CLI modes). The backend file's `@fileoverview` carries the per-category breakdown, including the two Web tab events.
 
 ### API Routes
 
-~199 handlers across 21 route files in `src/web/routes/`: system (45), sessions (32), cases (27), files (16), orchestrator (10), ralph (9), cron (9), admin (8), plan (8), respawn (7), webviews (6 + the `/webview/:cap/*` proxy), mux (5), push (4), scheduled (4, legacy `ScheduledRun`), me (2), teams (2), search (1), hooks (1), clipboard (1), status-telemetry (1), ws (1 WebSocket). Each file has `@fileoverview` with endpoint details.
+One module per domain in `src/web/routes/` (plus a barrel; `ls src/web/routes/` for the current list). Beyond the `/api` routes: the `/webview/:cap/*` proxy, the `/ws/voice/stream` relay and the terminal WebSocket. Each file has `@fileoverview` with endpoint details.
 
 **HTTP contract** (stable since 0.9.x, see `docs/versioning-policy.md`; full envelope/status/error-code/SSE spec in `docs/api-reference.md`): responses use the `ApiResponse<T>` envelope — `{ success: true, data? }` or `{ success: false, error, errorCode }` (`src/types/api.ts`). `/api/v1/*` is a versioned alias of `/api/*` (URL rewrite in `server.ts`).
 
@@ -306,26 +428,38 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 ## State Files
 
-All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, cron jobs/runs), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` + `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log), `update-status.json` (self-updater progress, polled across the service restart), `linked-cases.json`, `webviews.json` (saved web-tab dashboard URLs), `remote-hosts.json` + `remote-cases.json`, `docker-hosts.json` + `docker-cases.json` + `docker-exports/`, `subagent-window-states.json` + `subagent-parents.json` (subagent window layout, GET/PUT `/api/subagent-window-states`/`-parents`), `hook-secret` (per-instance), `users.json` (multi-user, mode 0600) + `admin-audit.jsonl`, `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI). Transient: `self-update-runner.sh`. Multi-user case spaces live OUTSIDE the data dir at `~/codeman-users/<username>/cases` (shared across instances like `~/codeman-cases`, override `CODEMAN_USER_SPACES_DIR`).
+All in `~/.codeman/`: `state.json` (sessions, settings, respawn, orchestrator, cron jobs/runs, owner tab layouts), `mux-sessions.json` (tmux recovery), `settings.json` (user prefs), `push-keys.json` + `push-subscriptions.json`, `session-lifecycle.jsonl` (audit log), `update-status.json` (self-updater progress, polled across the service restart), `docker-env-applied.json` (Compose deployment only: sha256 of the Dockerfile + compose file the running container was built from, written by `Start-Codeman.sh`, read by the self-updater's environment gate), `docker-build-source.json` (Compose deployment only: the checkout's HEAD commit and `package-lock.json` hash the `codeman-node-modules`/`codeman-dist` volumes currently reflect, written by both `Start-Codeman.sh` and a successful in-place self-update, compared to detect and refresh a volume left stale by an externally-triggered rebuild), `linked-cases.json`, `webviews.json` (saved web-tab dashboard URLs), `remote-hosts.json` + `remote-cases.json`, `docker-hosts.json` + `docker-cases.json` + `docker-exports/`, `subagent-window-states.json` + `subagent-parents.json` (subagent window layout, GET/PUT `/api/subagent-window-states`/`-parents`), `hook-secret` (per-instance), `users.json` (multi-user, mode 0600) + `admin-audit.jsonl`, `intents.json` (Read My Mind intent profiles, mode 0600), `certs/` (self-signed TLS for `--https`), `.env` (CODEMAN_USERNAME/PASSWORD fallback for the `codeman attach` CLI), `install.log` (installer step output, written by `install.sh`'s `run_step`) and `tailscale-rename` (the node name before `install.sh` renamed it, so uninstall can offer it back; both installer-route only). Transient: `self-update-runner.sh`. Multi-user case spaces live OUTSIDE the data dir at `~/codeman-users/<username>/cases` (shared across instances like `~/codeman-cases`, override `CODEMAN_USER_SPACES_DIR`).
 
 **Generated top-level dirs** (all gitignored — don't edit or commit): `dist/` (esbuild output), `out/`, `coverage/`, `test-results/`, `tmp/`, `screenshots-echo-diag/`. The committed gesture bundle (`src/web/public/gesture/gesture-codeman.js`) IS tracked, but its runtime wasm/model assets (`src/web/public/gesture/wasm/`, `*.task`) are fetched and gitignored.
 
 ## Testing
 
-**Never run the bare full suite** (`npm test` with no file argument): the default config includes the browser-driven suites (`test/mobile/**` and 3 other Playwright tests), which need a live server + chromium + environment-specific PNG baselines and will fail/hang locally. Run individual files, or `test:ci` for a broad sweep:
+**`npm test` is the gate and is safe to run bare** — it runs `config/vitest.ci.config.ts`, exactly what CI runs, so local green means CI green.
 
 ```bash
-npm test -- test/<specific-file>.test.ts         # Single file (SAFE, uses config/vitest.config.ts)
-npm test -- -t "pattern"                          # By name (SAFE)
-npm run test:ci                                   # Everything except browser/perf suites — what CI runs
-# npm test                                        # DON'T — includes browser/visual suites
+npm test                                          # The gate — what CI runs
+npm test -- test/<specific-file>.test.ts          # Single file
+npm test -- -t "pattern"                          # By name
 ```
 
-Raw `npx vitest` skips `config/vitest.config.ts`; always use `npm test --` or pass `--config config/vitest.config.ts`.
+Three suites are deliberately left out, because they cannot pass on an arbitrary machine. Each has its own runner, and a failure there means "not runnable here", not a regression:
 
-**Config**: Vitest with `globals: true`, `fileParallelism: false`. Timeout 30s, teardown 60s. `config/vitest.ci.config.ts` = same minus the browser/perf excludes — keep the two configs in sync when changing shared options.
+```bash
+npm run test:browser   # Playwright + chromium, live server; codex-predictive-echo also needs a real codex binary
+npm run test:mobile    # the above plus environment-specific PNG baselines (own config, own pretest vendor step)
+npm run test:perf      # wall-clock benchmarks — need an otherwise idle machine
+npm run test:all       # literally everything; fails ~87 tests on a clean master here, which is why it is not the default
+```
 
-**Tmux safety**: under vitest (`VITEST` env var, set automatically), `TmuxManager` no-ops ALL shell commands and becomes a pure in-memory mock — tests physically cannot create/kill/attach real tmux sessions (`IS_TEST_MODE` in `src/tmux-manager.ts`). Every docker IO path is no-op'd the same way. `Session` is test-gated too: instead of attaching a real tmux client, it spawns a raw-mode echo PTY (`TEST_PTY_SCRIPT` in `src/session.ts`), so integration tests get a live input/output loop that echoes each byte exactly once. `test/setup.ts` gives every test file a temporary `HOME`/`USERPROFILE` (all `homedir()`-derived state, `~/.codeman` and `~/codeman-cases` included, resolves into a per-file fixture; the Playwright browser cache path is preserved), and additionally strips `CODEMAN_PASSWORD`/`CODEMAN_USERNAME` (so auth state from the running instance can't leak into tests) and `CODEMAN_GESTURE` (a shell-exported gesture flag would flip render-injection assertions). ⚠️ Raw `npx vitest` without `--config` skips `setup.ts` and with it the temp-HOME isolation.
+⚠️ **`npm test` cannot see those suites**, so a change touching mobile/gesture/terminal-render behaviour needs the matching runner by hand — diff its FAIL list against master rather than reading it as pass/fail. That blind spot is what let two semantically-conflicting PRs merge green (see the on-screen-keyboard note above).
+
+⚠️ **A file filter must match the runner.** `npm test -- test/mobile/keyboard.test.ts` matches nothing and exits GREEN having run zero tests, because the gate's config excludes that path — an excluded file needs its own runner (`npm run test:mobile -- <file>`, `npm run test:browser -- <file>`, `npm run test:perf -- <file>`). Vitest treats "no files matched a filter" as success, so read the file count, not just the colour.
+
+Raw `npx vitest` skips the config (and with it `setup.ts`); always use `npm test --` or pass `--config`.
+
+**Config**: Vitest with `globals: true`, `fileParallelism: false`. Timeout 30s, teardown 60s. `config/vitest.config.ts` is the everything-config behind `test:all`; `config/vitest.ci.config.ts` is the gate and derives its excludes from `config/test-suites.ts`, which is also what `vitest.browser.config.ts` and `vitest.perf.config.ts` derive their includes from — so the exclusions and the runners cannot drift apart. Keep shared options in sync across them.
+
+**Tmux safety**: under vitest (`VITEST`), `TmuxManager` no-ops ALL shell commands (`IS_TEST_MODE` in `src/tmux-manager.ts`), docker IO is no-op'd likewise, and `Session` spawns an echo PTY (`TEST_PTY_SCRIPT`) instead of attaching tmux. `test/setup.ts` gives each file a temp `HOME`/`USERPROFILE` and strips `CODEMAN_PASSWORD`/`CODEMAN_USERNAME`, `CODEMAN_GESTURE` and `CODEMAN_INSTANCE`/`CODEMAN_DATA_DIR`/`CODEMAN_TMUX_SOCKET` (pinned by `test/test-env-isolation.test.ts`). ⚠️ `CODEMAN_DATA_DIR` overrides the temp HOME, so never drop its strip; strip `CODEMAN_INSTANCE` in the setup file, never in a hook (captured at first import). ⚠️ Delete case trees only via `safeRmHomeTree()`. ⚠️ Raw `npx vitest` without `--config` skips `setup.ts` and its isolation. → [architecture-invariants#test-isolation-tmux-docker-and-home](docs/architecture-invariants.md#test-isolation-tmux-docker-and-home)
 
 **Ports**: Pick unique ports manually, 3150+. Search `const PORT =` before adding new tests. Never 3000 (the live instance).
 
@@ -333,15 +467,15 @@ Raw `npx vitest` skips `config/vitest.config.ts`; always use `npm test --` or pa
 
 **Testing against the live instance**: prod is HTTPS-only on :3000 (`curl -sk https://localhost:3000/...`). ⚠️ `w1`/`w2`/`w3` are the user's REAL sessions — never send input to them. Create your own throwaway session (`POST /api/sessions` then `POST /api/sessions/:id/shell`; creation alone leaves `pid: null` and no pane), test against that, and `DELETE` it by exact id when done.
 
-**Respawn tests**: Use `MockSession` from `test/mocks/index.ts` (defined in `test/mocks/mock-session.ts`). **Route tests**: `app.inject({ method, url, payload })` in `test/routes/` — no live port needed. **Mobile tests**: Playwright suite in `test/mobile/` (136 device profiles). Browser-testing infra and practices: `docs/browser-testing-guide.md`.
+**Respawn tests**: Use `MockSession` from `test/mocks/index.ts` (defined in `test/mocks/mock-session.ts`). **Route tests**: `app.inject({ method, url, payload })` in `test/routes/` — no live port needed. **Mobile tests**: Playwright suite in `test/mobile/` (device profiles in `test/mobile/devices.ts`). Browser-testing infra and practices: `docs/browser-testing-guide.md`.
 
 ## Debugging
 
 ```bash
-tmux list-sessions                                 # List tmux sessions
-curl localhost:3000/api/sessions | jq              # Check sessions
-curl localhost:3000/api/status | jq                # Full app state
-curl localhost:3000/api/subagents | jq             # Background agents
+tmux -L codeman list-sessions                      # Codeman's own socket (bare `tmux` shows the default one)
+curl -sk https://localhost:3000/api/sessions | jq  # Check sessions (prod is HTTPS-only; dev on :3000 is plain http)
+curl -sk https://localhost:3000/api/status | jq    # Full app state
+curl -sk https://localhost:3000/api/subagents | jq # Background agents
 cat ~/.codeman/state.json | jq                     # Persisted state
 ```
 
@@ -351,12 +485,12 @@ Mobile screenshots: `~/.codeman/screenshots/`, accessed via `GET/POST /api/scree
 
 Target: 20 sessions, 50 agent windows at 60fps. Limits live in `src/config/` (terminal 32MB, text 1MB, messages 1000, max agents 500, max sessions 50, max SSE clients 100), most env-overridable.
 
-Two constraints worth knowing before you touch them: the env-derived PTY buffer trim is **clamped to ≤75% of max**, because a trim ≥ max would disable `BufferAccumulator` trimming entirely and make memory unbounded; and browser xterm scrollback is a **separate hardcoded 50k** (`DEFAULT_SCROLLBACK` in constants.js), deliberately lower than tmux's 100k history because 100k per tab is a mobile-memory hazard. The settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but **inert**; only `tmuxHistoryLimit` is wired live. → [architecture-invariants#buffers-uploads-and-terminal-history](docs/architecture-invariants.md#buffers-uploads-and-terminal-history), `docs/terminal-anti-flicker.md`
+Two constraints worth knowing before you touch them: the env-derived PTY buffer trim is **clamped to ≤75% of max**, because a trim ≥ max would disable `BufferAccumulator` trimming entirely and make memory unbounded; and browser xterm scrollback is a **separate hardcoded 50k** (`DEFAULT_SCROLLBACK` in constants.js), deliberately lower than tmux's 100k history because 100k per tab is a mobile-memory hazard. tmux <3.7 allocates `history-limit` at pane creation, while tmux 3.7+ can resize live panes (lowering the value can discard retained lines); already-evicted lines never return. The settings keys `terminalScrollbackLines`/`terminalBufferMaxBytes`/`terminalBufferTrimBytes` are schema-validated but **inert**; only `tmuxHistoryLimit` is wired. → [architecture-invariants#buffers-uploads-and-terminal-history](docs/architecture-invariants.md#buffers-uploads-and-terminal-history), `docs/terminal-anti-flicker.md`
 
 **Memory leaks (24+ hour sessions)**: use `CleanupManager`, clear Maps in `stop()`, guard async with `if (this.cleanup.isStopped) return`. Frontend: store handler refs, clean in `close*()`. Use `LRUMap` for bounded caches, `StaleExpirationMap` for TTL cleanup. Verify: `npm test -- test/memory-leak-prevention.test.ts`.
 
 ## Scripts & Tunnel
 
-**`install.sh`** (repo root, 69KB) is the public entry point: `curl -fsSL <raw url> | bash` installs Node/tmux if missing, clones to `~/.codeman/app`, builds, and offers a systemd/launchd service. The network-access prompt is 3-way: **Tailscale** (loopback bind + guided `tailscale serve --bg <port>` HTTPS setup: install/login/operator/tailnet-HTTPS-toggle, then curl-verified end-to-end), **LAN** (0.0.0.0 + password prompt), or **local-only**; it preserves the existing binding on re-runs via `read_existing_binding()`. Tailscale state is detected dynamically from `tailscale serve status --json` (no marker files); the installer must NEVER `tailscale serve reset` or touch serve mappings other than 443→Codeman's port (users have unrelated serve config). `install.sh update`, `install.sh uninstall`, and `install.sh tailscale` (retrofit Tailscale access onto an existing install) also exist; `CODEMAN_NONINTERACTIVE=1` approves system changes for automation, `CODEMAN_TAILSCALE=1` presets the Tailscale choice (never installs Tailscale non-interactively).
+**`install.sh`** (repo root) is the public `curl | bash` installer: it installs Node/tmux/git/build tools, clones to `~/.codeman/app`, builds, and offers a systemd/launchd service, asking every question BEFORE the unattended build (log in `~/.codeman/install.log`). Network access is Tailscale / LAN / local-only; re-runs preserve the existing binding AND password (`read_existing_binding()`). ⚠️ Compose the hand-start env only in `start_command_hint`/`export_bind_env`, and call `stop_background_helpers` before `exec`. ⚠️ Tailscale rename is opt-in (default NO, never under `--yes`/non-interactive); NEVER `tailscale serve reset`, touch a mapping it did not create, run `tailscale funnel` or advertise a Service (`test/install-sh-invariants.test.ts`). ⚠️ Stay **bash 3.2** clean (no `declare -A`, `mapfile`, namerefs, `${x,,}`, here-strings, empty-array expansion under `set -u`). ⚠️ Execute only commands from the generated CLI block (`CLI_INSTALL_CMD_TRUSTED`, `npm run generate:cli-catalog`). → [architecture-invariants#installsh-the-public-installer](docs/architecture-invariants.md#installsh-the-public-installer)
 
 Other key scripts: `scripts/tmux-manager.sh` (safe tmux mgmt), `scripts/tunnel.sh [quick|named] start|stop|status|url` (quick = random trycloudflare URL, default; `named setup|enable` = fixed-hostname tunnel via `scripts/codeman-tunnel-named.service`; bare `start|stop|url` still means quick), `scripts/run-beta.sh` (isolated beta instance), `scripts/build-agent-image.mjs` (docker base image), `scripts/self-update.sh` (detached updater). Production services: `scripts/codeman-web.service`, `scripts/codeman-tunnel.service`. **Always set `CODEMAN_PASSWORD`** before exposing via tunnel.

README.md

@@ -5,7 +5,7 @@
 <h2 align="center">Mission control for AI coding agents</h2>
 
 <p align="center">
-  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Gemini &bull; Terminal - One Dashboard &bull; Any Device</em>
+  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Antigravity &bull; Gemini &bull; Pi &bull; Grok &bull; DeepSeek &bull; OMP &bull; Terminal - One Dashboard &bull; Any Device</em>
 </p>
 
 <p align="center">
@@ -19,6 +19,10 @@
   <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
 </p>
 
+<p align="center">
+  ⭐ <strong>Like Codeman? <a href="https://github.com/Ark0N/Codeman">Give it a star on GitHub!</a></strong> It takes one click and helps more people find the project. ⭐
+</p>
+
 <p align="center">
   <strong>English</strong> &bull; <a href="README.zh-CN.md">简体中文</a>
 </p>
@@ -27,7 +31,7 @@
   <img src="docs/images/subagent-demo-20260724.gif" alt="Codeman — parallel subagent visualization" width="900">
 </p>
 
-**Codeman** is a self-hosted mission control for AI coding agents. It spawns Claude Code, OpenCode, Codex, or Gemini CLI inside persistent tmux sessions, streams the real terminal to any browser, and keeps agents productive after you walk away: it re-prompts on idle, resumes when a usage limit resets, runs scheduled jobs, and shows every background agent working in real time.
+**Codeman** is a self-hosted mission control for AI coding agents. It spawns Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, Grok, DeepSeek Harness, or OMP inside persistent tmux sessions, streams the real terminal to any browser, and keeps agents productive after you walk away: it re-prompts on idle, resumes when a usage limit resets, runs scheduled jobs, and shows every background agent working in real time.
 
 Get started in one line (macOS & Linux, Windows via WSL):
 
@@ -42,7 +46,7 @@ codeman web
 
 The installer asks before every system change, and re-running the same line updates in place. Full details: [Quick Start - Installation](#quick-start---installation).
 
-- **One dashboard, four CLIs** - run [Claude Code, OpenCode, Codex, or Gemini](#more-features) per session (plus plain shell), locally, [in Docker](#isolated-docker-sessions), or [over SSH](#remote-ssh-sessions)
+- **One dashboard, nine CLIs** - run [Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, Grok, DeepSeek, or OMP](#more-features) per session (plus plain shell), locally, [in Docker](#isolated-docker-sessions), or [over SSH](#remote-ssh-sessions), with your own dashboards open as [web tabs](#more-features) beside them
 - **Truly phone-friendly** - a [touch-optimized terminal](#mobile-optimized-web-ui) with instant local echo, QR login, swipe navigation, and push notifications
 - **Runs while you sleep** - [idle detection + respawn cycling](#respawn-controller) and auto-resume when a subscription limit resets, for 24+ hour unattended runs
 - **See your agents think** - [live floating windows](#live-agent-visualization) for every subagent and teammate, with real-time transcripts
@@ -61,14 +65,15 @@ The installer asks before every system change, and re-running the same line upda
 curl -fsSL https://getcodeman.com/install | bash
 ```
 
-This installs Node.js and tmux if missing, clones Codeman to `~/.codeman/app`, and builds it. A few things worth knowing:
+This installs Node.js, tmux and a build toolchain if missing (node-pty ships no Linux prebuilds, so it compiles from source), clones Codeman to `~/.codeman/app`, and builds it. It looks at what is already on the machine, asks at most three questions, then does all the work unattended and ends on the URL with a QR code for your phone. A few things worth knowing:
 
-- **It asks first.** Every system change (package installs, AI CLI download) is prompted, and a menu at the end lets you choose: run Codeman in this terminal, install it as a background service (systemd/launchd, auto-start on boot), or don't start yet. Nothing runs in the background unless you pick it.
-- **Network or local-only, your choice.** The installer asks whether the dashboard should be reachable from other devices on your network (`0.0.0.0`, the default, with a strongly recommended password prompt) or from this machine only (`127.0.0.1`, safest). Skipping the password on a network bind requires an explicit confirmation and ends with a loud warning. A bare `codeman web` started by hand still defaults to loopback.
-- **Re-run to update.** The same one-liner updates a finished install in place: local changes in `~/.codeman/app` are stashed (never discarded), and a running service is restarted and verified. If a first install was interrupted, re-running resumes the full setup instead. `install.sh update` and `install.sh uninstall` also exist.
-- **CI / headless:** without a terminal attached, steps that would change your system abort with instructions instead of running silently. Set `CODEMAN_NONINTERACTIVE=1` to approve them for automation.
+- **Three questions, all up front.** How the dashboard is reached, optionally what to call this machine on your tailnet, and whether to run Codeman as a background service (systemd/launchd, auto-start on boot; Enter says yes). Everything that needs you, including one consent for all missing packages, one sudo password, and the Tailscale login, happens before the build, so you can walk away while it compiles.
+- **How it's reachable, your choice.** **Tailscale** (loopback bind fronted by `tailscale serve`, so you get `https://<machine>.<tailnet>.ts.net` with a real certificate and your tailnet as the login, no password needed), **any device on your network** (`0.0.0.0`, with a strongly recommended password prompt), or **this machine only** (`127.0.0.1`, safest). Skipping the password on a network bind requires an explicit confirmation and ends with a loud warning. The highlighted default reflects what is already on the machine (Tailscale when it is already connected, your existing binding on a re-run), and a bare Enter never pulls in new software. If another app already owns `:443` on your node, Codeman goes under `https://<machine>.<tailnet>.ts.net/codeman` or on a second port instead of replacing it. A bare `codeman web` started by hand still defaults to loopback.
+- **The name is yours to choose.** By default the URL uses the machine's existing tailnet name. Answering yes to the second question renames the machine to `codeman-<hostname>` (which also renames it for SSH, so the default is no); `install.sh name` does it later.
+- **Re-run to update.** The same one-liner updates a finished install in place: local changes in `~/.codeman/app` are stashed (never discarded), and a running service is restarted and verified. If a first install was interrupted, re-running resumes the full setup instead. `install.sh status` prints the URLs and the QR code again; `install.sh update`, `install.sh tailscale` and `install.sh uninstall` also exist.
+- **Flags for the impatient.** `curl -fsSL https://getcodeman.com/install | bash -s -- --tailscale --service` answers the questions from the command line (`--lan`, `--local`, `--run`, `--no-start`, `--name <n>`, `--port <n>`, `--yes` too). **CI / headless:** without a terminal attached, steps that would change your system abort with instructions instead of running silently; set `CODEMAN_NONINTERACTIVE=1` to approve them for automation.
 
-You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), or [Gemini CLI](https://github.com/google-gemini/gemini-cli) (any combination works). The installer detects whichever of the four is present; if none is found, it offers to install Claude Code or OpenCode, or you can skip and install one yourself later. After install:
+You'll need at least one AI coding CLI installed — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Pi](https://pi.dev), [Grok Build](https://github.com/xai-org/grok-build), [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), or [OMP](https://github.com/can1357/oh-my-pi) (any combination works; Gemini CLI is enterprise-only since Google's consumer cutover, and Antigravity is its successor). The installer detects whichever of the nine is present; if none is found, it offers to install any of them from a menu (DeepSeek excepted, since its npm package installs only a launcher with no runnable profile), or you can skip and install one yourself later. After install:
 
 ```bash
 codeman web
@@ -82,12 +87,34 @@ codeman users add alice --admin      # create the first admin account
 codeman web --multiuser              # named logins + per-user case spaces
 ```
 
+**Prefer Docker Compose?** A local-image Compose deployment ships in `docker/`: copy `docker/.env.example` to `docker/.env`, set `CODEMAN_PASSWORD`, then run `bash docker/Start-Codeman.sh` on Linux. Codeman runs in a container and spawns Docker cases as sibling containers through the host socket. After updating, run the script again rather than a plain `docker compose up`, so the rebuilt image, refreshed volumes and entrypoint arrive together. See the [Docker deployment guide](docker/README.md) for direct Compose commands, storage and networking options.
+
 Details in [Multi-User Mode](#multi-user-mode-opt-in) below.
 
 <details>
-<summary><strong>Run as a background service</strong></summary>
+<summary><strong>Keep it running in the background</strong></summary>
 
-The installer's final menu sets this up for you (option 2) and verifies the service actually comes up before claiming success. To configure it manually instead:
+To outlive the shell you started it in, without setting anything up:
+
+```bash
+codeman web -d          # detach; logs to ~/.codeman/web.log
+codeman web --status    # is it up, and on which pid
+codeman web --stop      # graceful SIGTERM; agents keep running in tmux
+```
+
+`-d` waits until the server actually answers before reporting success, and refuses to start a second one on the same data dir (two servers sharing a tmux socket attach to each other's sessions).
+
+To have it come back after a reboot, install it as a service instead. The installer's final menu does this for you (option 2); `codeman service` is the equivalent for an `npm i -g aicodeman` install:
+
+```bash
+codeman service install     # systemd user unit (Linux) or LaunchAgent (macOS)
+codeman service status
+codeman service uninstall
+```
+
+`service install` writes the unit with your current PATH baked in, which matters more than it sounds: launchd hands a job `/usr/bin:/bin:/usr/sbin:/sbin`, so a Homebrew or nvm `node`, `tmux` or `claude` is invisible to a hand-written plist. It never copies `CODEMAN_PASSWORD` into the unit file; add that yourself if the service needs auth.
+
+To write the unit by hand instead:
 
 **Linux (systemd):**
 
@@ -151,7 +178,7 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
 wsl bash -c "curl -fsSL https://getcodeman.com/install | bash"
 ```
 
-Codeman requires tmux, so Windows users need [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). If you don't have WSL yet: run `wsl --install` in an admin PowerShell, reboot, open Ubuntu, then install your preferred AI coding CLI inside WSL ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)). After installing, `http://localhost:3000` is accessible from your Windows browser.
+Codeman requires tmux, so Windows users need [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). If you don't have WSL yet: run `wsl --install` in an admin PowerShell, reboot, open Ubuntu, then install your preferred AI coding CLI inside WSL ([Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Pi](https://pi.dev), [Grok Build](https://github.com/xai-org/grok-build), [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), or [OMP](https://github.com/can1357/oh-my-pi)). After installing, `http://localhost:3000` is accessible from your Windows browser.
 
 </details>
 
@@ -187,17 +214,17 @@ The most responsive AI coding agent experience on any phone. Full xterm.js termi
 <tr><td>Password typing on phone</td><td><b>QR code scan — instant auth</b></td></tr>
 </table>
 
-- **Keyboard accessory bar** — `/init`, `/clear`, `/compact` quick-action buttons above the virtual keyboard; destructive commands require a double-press to confirm, so you never fire one by accident
+- **Keyboard accessory bar** — `/init`, `/clear`, `/compact` quick-action buttons above the virtual keyboard; destructive commands require a double-press to confirm, so you never fire one by accident; on Codex sessions the bar also shows `⇧←` / `⇧→` (Shift+Left / Shift+Right: edit the last queued message / return through the prompt stack)
 - **Dedicated Enter button** — replays the keypress through the terminal, so text buffered by local echo is flushed first rather than stranded
 - **Swipe navigation & smart keyboard handling** — swipe left/right to switch sessions; toolbar and terminal shift up when the keyboard opens (`visualViewport` API)
-- **Built for phones** — safe-area insets for notch and home indicator, 44px touch targets, bottom-sheet case picker, native momentum scrolling
+- **Built for phones** — safe-area insets for notch and home indicator, 44px touch targets, bottom-sheet case picker, native momentum scrolling; on a folding phone (iPhone Duo) dialogs stay clear of the hinge, and opening or closing the device is never mistaken for the keyboard
 
 ```bash
 codeman web --https
 # Open on your phone: https://<your-ip>:3000
 ```
 
-> `localhost` works over plain HTTP. Use `--https` when accessing from another device, or use [Tailscale](https://tailscale.com/) (recommended): the installer can set it up for you (choose **Tailscale** at the network-access prompt, or run `bash ~/.codeman/app/install.sh tailscale` on an existing install). That gives you `https://<your-machine>.<tailnet>.ts.net` with a real certificate: private to your tailnet, no password required, and PWA install + push notifications work on your phone.
+> `localhost` works over plain HTTP. Use `--https` when accessing from another device, or use [Tailscale](https://tailscale.com/) (recommended): the installer can set it up for you (choose **Tailscale** at the network-access prompt, or run `bash ~/.codeman/app/install.sh tailscale` on an existing install). That gives you `https://<your-machine>.<tailnet>.ts.net` with a real certificate: private to your tailnet, no password required, and PWA install + push notifications work on your phone. The installer ends on that URL with a QR code to scan, and `bash ~/.codeman/app/install.sh status` prints it again any time.
 
 ### Secure QR Code Authentication
 
@@ -220,6 +247,8 @@ codeman web                       # localhost:3000 (loopback only — safe defau
 codeman web --port 8080           # custom port (or set CODEMAN_PORT)
 codeman web --https               # self-signed TLS (only needed for remote access)
 codeman web -H 0.0.0.0            # bind LAN — REQUIRES CODEMAN_PASSWORD (see Security)
+codeman web -d                    # detach: survives closing the shell (--status, --stop)
+codeman service install           # systemd/launchd service: comes back after reboots
 ```
 
 Open the printed URL. The page is a single dashboard; everything below happens there.
@@ -230,16 +259,16 @@ Click **+ New Session** (or **Quick Start**). A session is one AI CLI running in
 
 | Field                        | What it does                                                                                                        |
 | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| **Working directory / case** | The folder the agent operates in. A "case" is just a named working dir Codeman remembers.                           |
-| **CLI / run mode**           | `Claude` (default), `OpenCode`, `Codex`, `Gemini`, or `Terminal` (plain shell).                                     |
-| **Model**                    | Per-session model (App Settings → Claude Model). A soft default — `/model` still works in-session.                  |
+| **Working directory / case** | The folder the agent operates in. A "case" is just a named working dir Codeman remembers. **Add Case** creates one from scratch, links an existing folder, or clones a GitHub repo straight into one (**Clone Repo**). |
+| **CLI / run mode**           | `Claude` (default), `OpenCode`, `Codex`, `Antigravity`, `Gemini`, `Pi`, `Grok`, `DeepSeek`, `OMP`, or `Terminal` (plain shell). |
+| **Model**                    | Per-session model (App Settings → Models → New Claude sessions). A soft default — `/model` still works in-session.                  |
 | **Effort / Ultracode**       | Reasoning effort (`low`–`max`) or `ultracode` for dynamic multi-agent workflows. Switchable anytime with `/effort`. |
 
 Hit start — Codeman spawns the CLI via a real PTY and streams it to your browser over SSE.
 
 ### 3. Read the dashboard
 
-- **Tabs (top)** — one per session. `Alt+1`-`9` to jump, `Ctrl+Tab` for next, drag to reorder (tab order syncs across your devices).
+- **Tabs (top)** — one per session. `Alt+1`-`9` to jump, `Ctrl+Tab` for next, drag to reorder (tab order syncs across your devices). Prefer a list? **App Settings → Appearance → Tabs** moves it into a left sidebar with a filter box (`Alt+B` collapses it) or a vertical rail whose rows sort by activity: blocked on you first, then longest running, then most recently quiet.
 - **Terminal (center)** — a real `xterm.js` terminal; full TUIs render correctly. Type directly and press **Enter** to send. `Shift+Enter` inserts a newline.
 - **Side panels** — Respawn, Orchestrator, Cron, Subagents, Settings (toggled from the toolbar).
 
@@ -247,8 +276,10 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
 
 - **Type prompts** straight into the terminal — input is delivered exactly-once even across reconnects (a dropped link never loses or double-sends a prompt).
 - **Paste or drag-and-drop images** directly into the session.
-- **Voice input** — `Ctrl+Shift+V` (Deepgram Nova-3, with auto-silence stop).
-- **Attachments** — register external files/docs and preview Office/PDF inline.
+- **Voice input** — `Ctrl+Shift+V` (Deepgram Nova-3, or this machine's Claude Code login with no API key; auto-silence stop).
+- **Attachments** — register external files/docs and preview Office/PDF inline; any file path an agent prints is clickable, in the terminal and in the chat view.
+- **When it needs you** — the tab turns yellow (waiting for input) or red (a question is blocking). The **Approvals Inbox** _(opt-in)_ queues every pending prompt across sessions, answerable from the header bell or the phone home screen, and 🧠 **Read My Mind** _(opt-in)_ drafts your next prompt from the case's goals and recent work.
+- **Copy what you see** — `Shift+drag` selects text even while the CLI owns the mouse, right-click copies it, and Auto Copy _(opt-in)_ copies a selection the moment you release it.
 
 ### 5. Make it autonomous
 
@@ -256,19 +287,20 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
 | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
 | **Respawn**      | Long unattended runs — auto-restarts the CLI on idle/limit, with adaptive timing. Presets: `solo-work`, `overnight-autonomous`, … | Respawn tab                                                         |
 | **Orchestrator** | Turn one goal into a phased plan and drive it to completion across agents.                                                        | Orchestrator panel                                                  |
-| **Cron**         | Saved, named jobs on a schedule (`once`/`interval`/`daily`/`weekly`) that spawn a session and send a prompt when due.             | ⏰ Cron button _(opt-in: App Settings → Display → Header Displays)_ |
+| **Cron**         | Saved, named jobs on a schedule (`once`/`interval`/`daily`/`weekly`) that spawn a session and send a prompt when due.             | ⏰ Cron button _(opt-in: App Settings → Header & Panels → Scheduling)_ |
 | **Auto-resume**  | Automatically continue after a subscription rate-limit resets.                                                                    | Respawn tab (top)                                                   |
 
 ### 6. Reach it from anywhere
 
 - **Phone/tablet** — the UI is fully touch-optimized; scan the desktop **QR code** to log in without typing a password.
 - **Outside your network** — `./scripts/tunnel.sh start` opens a Cloudflare tunnel (set `CODEMAN_PASSWORD` first).
-- **SSH** — the `sc` chooser attaches to any session from a terminal (`sc` interactive, `sc 2` quick-attach, `sc -l` list).
+- **SSH** — `codeman tui` is a full-screen dashboard in the terminal (`codeman tui --list` to list, `codeman tui 2` to attach straight to one).
 
 ### 7. Operate & maintain
 
-- **App Settings** — model, effort, permission startup mode, theme/skin, notifications, display toggles, per-CLI options, a synced custom display name, and per-device English/Simplified Chinese UI language.
-- **Self-update** — git-clone installs update in place from **Settings → Updates**.
+- **App Settings** — model, effort, permission startup mode, theme/skin, terminal font family and weight, entrance animations, notifications, display toggles, per-CLI options, a synced custom display name, and per-device English/Simplified Chinese UI language.
+- **Run it in the background** — `codeman web -d` detaches from your shell (`--status`, `--stop`); `codeman service install` makes it a systemd user unit / macOS LaunchAgent that survives reboots. Both verify the server actually answers before reporting success, and both refuse to start a second server on one data dir. See [Keep it running in the background](#quick-start---installation).
+- **Self-update** — git-clone installs update in place from **App Settings → System → Updates**.
 - **Deploy your own changes** — see [Development](#development).
 
 > ⚠️ **Safety:** if you're working _inside_ a Codeman-managed session (`echo $CODEMAN_MUX` → `1`), never run `tmux kill-session` / `pkill claude` directly — use the web UI or `./scripts/tmux-manager.sh`.
@@ -383,6 +415,14 @@ The title is templated into the served HTML on first byte, so it's correct from
 | **110k tokens** | Auto `/compact` | Context summarized, work continues |
 | **140k tokens** | Auto `/clear`   | Fresh start with `/init`           |
 
+### Tab Alerts
+
+<p align="center">
+  <img src="docs/images/tab-alerts-glow-20260815.gif" alt="Session tabs: a regular active tab beside a yellow waiting-for-input tab and a red needs-decision tab, both with a breathing glow" width="900">
+</p>
+
+Every tab tells you its state at a glance. A running session keeps its green status dot. When a session stops and waits for input, its tab turns **yellow**: steady ring, tinted background, yellow dot, with a slow breathing glow on top. When a permission prompt or question is **blocking** the agent, the tab turns **red** with a faster pulse. The base tint never blinks off, so even a split-second glance (or a screenshot) reads the true state; the ring stays visible while the tab is selected, and a page reload re-arms pending alerts from the server, so a blocked session can never hide behind a fresh-looking tab.
+
 ### Notifications
 
 Real-time desktop alerts when sessions need attention — `permission_prompt` and `elicitation_dialog` trigger critical red tab blinks, `idle_prompt` triggers yellow blinks. Click any notification to jump directly to the affected session. Hooks auto-configured per case directory.
@@ -403,17 +443,24 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 
 ## More Features
 
-- **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
-- **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, or **Gemini** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `GEMINI_*`/`GOOGLE_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md)
-- **Docker sessions** — run a case inside an isolated, hardened container. One checkbox on **Create New** spins up a container with sensible defaults and starts the agent inside it; multiple sessions share one per-case container; export a container + its workspace to a portable `.tar.gz` to move it to another machine. See [`docs/docker-cases.md`](docs/docker-cases.md)
-- **Remote SSH sessions** — point a case at another machine and run the agent there inside a durable remote tmux: survives SSH drops, auto-reconnects, and can discover + attach sessions already running on the host. See [`docs/remote-sessions.md`](docs/remote-sessions.md)
+- **Background daemon & service install** — `codeman web -d` runs the server detached with a pidfile, `~/.codeman/web.log`, and verified startup (it polls the server until it answers, so a port clash never reads as success); `codeman service install` writes a systemd user unit (Linux) or LaunchAgent (macOS) with your shell's PATH baked in, so an nvm or Homebrew `node`, `tmux` and `claude` are actually found. Secrets are never written into unit files
+- **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → System → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
+- **Clone a GitHub repo as a case** — paste a repository URL into **Add Case → Clone Repo** and Codeman clones it into `~/codeman-cases/<name>` and registers it as a normal case, ready to run an agent in. It preflights the URL while you type (tells you whether it can be cloned anonymously and offers the repo's real branches and tags for the optional branch/tag field), fills the case name in from the URL, and lets you pick which CLI the Run button should use. Public repositories over `https://`; Codeman never collects or stores credentials
+- **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, **Antigravity**, **Gemini**, **Pi**, **Grok**, **DeepSeek Harness**, or **OMP** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `ANTIGRAVITY_*` vs `GEMINI_*`/`GOOGLE_*` vs `PI_*` vs `GROK_*`/`XAI_*` vs `DSH_*`/`DEEPSEEK_*` vs `OMP_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md), [`docs/pi-integration.md`](docs/pi-integration.md), [`docs/grok-integration.md`](docs/grok-integration.md), [`docs/deepseek-integration.md`](docs/deepseek-integration.md) and [`docs/omp-integration.md`](docs/omp-integration.md)
+- **Custom model endpoints** _(new in 1.29.0, HTTP API for now)_ — point a session's CLI at any OpenAI-compatible endpoint instead of its native backend: a local llama.cpp, llama-swap, Ollama or vLLM box, or a cloud gateway such as Azure AI Foundry or OpenRouter. Save an endpoint once (`POST /api/model-endpoints`; its models are discovered from `/v1/models`), apply it to a session (`POST /api/sessions/:id/custom-model`), and the CLI restarts in place on that endpoint. Verified live for Claude, OpenCode, Pi, Grok and OMP; Codex, Gemini and DeepSeek have documented gaps, Antigravity has no mechanism. A toolbar picker is the follow-up. See [`docs/custom-model-endpoints.md`](docs/custom-model-endpoints.md)
+- **Web tabs** — open Grafana, Uptime Kuma, a Vite dev server or any dashboard URL as a tab beside your sessions (Run dropdown → **Web / URL** → **Add URL**). Dashboards are proxied through Codeman's own origin, so an `http://` target works from a phone over HTTPS and through the tunnel, single-page apps route on their own paths, and a frame that reloads recovers itself. A `localhost` link an agent prints opens as a web tab automatically. See [`docs/web-tabs.md`](docs/web-tabs.md)
+- **Docker sessions** — run a case inside an isolated, hardened container. One checkbox on **Create New** spins up a container with sensible defaults and starts the agent inside it; multiple sessions share one per-case container, or attach a case to a container you already run; export a container + its workspace to a portable `.tar.gz` to move it to another machine. See [`docs/docker-cases.md`](docs/docker-cases.md)
+- **Remote SSH sessions** — point a case at another machine and run the agent there inside a durable remote tmux: survives SSH drops, auto-reconnects, and can discover + attach sessions already running on the host; file previews and downloads come over the same ssh connection. See [`docs/remote-sessions.md`](docs/remote-sessions.md)
 - **Effort & Ultracode** — set a per-session default effort (`low`–`max`) or enable **ultracode** (dynamic multi-agent workflows). Soft defaults only — switchable anytime with `/effort` in-session. Extended-thinking budget is configurable too
-- **Voice input** — dictate prompts with Deepgram Nova-3 (Web Speech API fallback): toggle recording, auto-silence stop, live level meter (`Ctrl+Shift+V`)
+- **Voice input** — dictate prompts with Deepgram Nova-3, or through this machine's Claude Code login with no API key at all (App Settings → Voice; Web Speech API fallback): toggle recording, auto-silence stop, live level meter (`Ctrl+Shift+V`)
 - **Image input** — paste or drag-and-drop images straight into a session
-- **Gesture control** _(opt-in)_ — a MediaPipe hand-tracking overlay to grab/drag session windows and pinch buttons, hands-free. Enable with `CODEMAN_GESTURE=1` + App Settings → Display
+- **Gesture control** _(opt-in)_ — a MediaPipe hand-tracking overlay to grab/drag session windows and pinch buttons, hands-free. Enable with `CODEMAN_GESTURE=1` + App Settings → Terminal & Input
 - **Multi-monitor span** _(macOS)_ — one click opens a browser window maximized across all displays, so floating agent/gesture panels can cross the physical seam
-- **File Viewer button** _(opt-in)_ — a header button that toggles the built-in file browser panel with one tap; enable under App Settings → Display → Header Displays
-- **CJK / IME input** — full composition support for Chinese / Japanese / Korean
+- **File Viewer button** _(opt-in)_ — a header button that toggles the built-in file browser panel with one tap; enable under App Settings → Header & Panels → Header buttons
+- **CJK / IME input** — full composition support for Chinese / Japanese / Korean, with Ctrl- and Alt-modified navigation keys passed through to the CLI
+- **Plan usage in the header** — live Claude subscription usage (the 5-hour and weekly windows) from a statusline exporter Codeman hands to `claude` at spawn and never writes into your settings files, plus Codex limits from its own app-server; per device, on for desktops and off for phones
+- **Session list, your way** — the header strip, a left sidebar with a filter box, or a vertical rail whose detailed rows carry created and state stamps and sort by activity; the phone home screen and the desktop home rail use the same order
+- **Terminal looks** — seven skins, four of them light, per-device font family and weight (the bundled JetBrains Mono covers weights 100 to 800), and opt-in entrance animations for tabs, agent windows, the terminal pane and connection lines
 - **OS notifications & hostname-aware titles** — desktop alerts and tab titles are prefixed `codeman:<host>` so multi-host setups stay unambiguous
 
 ---
@@ -426,7 +473,8 @@ Run a case inside its own hardened Docker container instead of directly on your
 - **Resource templates** — expand the checkbox for a **Small / Medium / Large / GPU** preset (memory, CPUs, GPU), or set your own. **Disk is elastic** — storage grows as data flows in, no fixed cap.
 - **Shared per-case container** — many sessions can `docker exec` into the same container; killing one session never tears the container out from under the others.
 - **Hardened by default** — non-root, `--cap-drop ALL`, `no-new-privileges`, PID/memory caps, never `--privileged` or the docker socket; a **sealed** profile (no host credentials, network off) is one toggle away.
-- **Seamless auth, isolated credentials** — your host Claude / Codex / Gemini / OpenCode logins work inside the container out of the box: credentials are seeded (copied) in at launch and onboarding/trust prompts are pre-answered, so no login wizard appears. The container keeps its own copies and never writes back to your host credential stores; only conversation transcripts are shared, and exports never capture secrets.
+- **Seamless auth, isolated credentials** — your host Claude / Codex / Antigravity / Gemini / OpenCode / Pi / Grok / OMP logins work inside the container out of the box: credentials are seeded (copied) in at launch and onboarding/trust prompts are pre-answered, so no login wizard appears. The container keeps its own copies and never writes back to your host credential stores; only conversation transcripts are shared, and exports never capture secrets.
+- **Attach to a container you already run** — tick **Attach to an existing container** on the Docker panel to link a case to it instead of creating one. Codeman only `exec`s into it and never starts, stops, restarts or removes it; one adopted container can back several cases at different directories, and **copy an existing case** pre-fills the form from a sibling. Admin-only in multi-user mode, since the container's mounts belong to whoever started it.
 - **Move it to another machine** — export a container's whole environment (toolchain + workspace) to a portable `.tar.gz`, `docker load` it on the other side, and import it into a fresh case.
 - **Durable** — reconnect after a restart lands back in the same live agent; a container stop/reboot resumes the conversation from the bind-mounted transcript.
 
@@ -443,6 +491,7 @@ Point a case at another machine and run the agent **there**, over SSH, with the
 - **Discover & attach**: list the `codeman-*` sessions already running on a host (started by that machine's own Codeman, or by another operator) and attach to one. Attached sessions you don't own **detach on tab close, never kill**.
 - **Shared sessions**: several clients can attach the same remote session at different window sizes without clamping each other; discovery shows a "shared" badge with the client count.
 - **Injection-safe**: every ssh command line flows through a single shell-escaping builder, and host/path/identity fields are schema-guarded.
+- **Files too**: previews, downloads and text reads in a remote case go over the same ssh connection (one `realpath` + `stat` probe, then a streamed `cat`, `Range` seeking included), so a clicked path opens the file on the machine the agent is on. Nothing is copied to the Codeman host; editing and Office previews answer a clear 400 instead of a misleading 404.
 
 Set it up under **New Case → Remote** (host, user, identity file, optional jump host). Full design: [`docs/remote-sessions.md`](docs/remote-sessions.md).
 
@@ -496,7 +545,7 @@ The script auto-installs a systemd user service on first run. The tunnel URL is
 systemctl --user enable codeman-tunnel
 loginctl enable-linger $USER
 
-# Or via the Codeman web UI: Settings → Tunnel → Toggle On
+# Or via the Codeman web UI: App Settings → System → Remote access → Cloudflare Tunnel
 ```
 
 </details>
@@ -598,7 +647,7 @@ By default Codeman launches sessions with `--dangerously-skip-permissions`, so t
 - **Loopback by default** — the server binary binds `127.0.0.1`, reachable only from the same machine, so the no-password default is safe out of the box (the guided installer asks about network access and configures the binding + password for you). Binding a non-loopback host without `CODEMAN_PASSWORD` _starts but prints a loud warning_ with three concrete fixes (set a password, loopback + an authenticated tunnel, or explicitly acknowledge with `--allow-unauthenticated-network`)
 - **Optional auth, real sessions** — HTTP Basic via `CODEMAN_USERNAME` (default `admin`) / `CODEMAN_PASSWORD`. Success issues an opaque 256-bit `codeman_session` cookie (`randomBytes(32)`) — validated server-side, not client-signed, so it can't be forged offline (24h TTL, auto-extend, device-context audit log)
 - **Per-IP rate limiting** — 10 failed attempts → `429` with `Retry-After` (15-min decay). A valid cookie or correct password recovers _immediately_ even while an attacker hammers the same IP — important because all tunnel traffic shares one loopback IP. QR auth has its own separate limiter
-- **Configurable permission mode** - `--dangerously-skip-permissions` is only the default. **App Settings → Claude CLI → Startup Mode** can switch new sessions to Anthropic's classifier-guarded `auto` mode (low-prompt, needs Claude Code 2.1.207+), `normal` prompting, or an explicit allowed-tools list. In multi-user mode, non-granted users are forced to `auto`, and shell sessions / skip-permissions require an explicit per-user grant
+- **Configurable permission mode** - `--dangerously-skip-permissions` is only the default. **App Settings → Agents & CLIs → Claude → Startup Mode** can switch new sessions to Anthropic's classifier-guarded `auto` mode (low-prompt, needs Claude Code 2.1.207+), `normal` prompting, or an explicit allowed-tools list. In multi-user mode, non-granted users are forced to `auto`, and shell sessions / skip-permissions require an explicit per-user grant
 
 ### Always-on browser hardening (v0.9.5)
 
@@ -612,8 +661,8 @@ These run for **every** request — before auth, even on the default no-password
 
 ### Input, files & headers
 
-- **Schema-validated inputs** — every API body is checked with Zod v4 schemas; a `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` env-prefix allowlist gates which settings each CLI can receive
-- **Path containment** — file routes `realpath` before boundary checks (no TOCTOU); `..`, absolute paths, and symlinks resolving outside the working dir are rejected. Caps: 10 MB text preview / 50 MB raw & download; `/api/download` blocklists sensitive paths (`.env`, `*credentials*`, `~/.ssh/`, `.aws/credentials`). SVG/HTML is served `octet-stream` + `nosniff` + attachment so it downloads rather than executes
+- **Schema-validated inputs** — every API body is checked with Zod v4 schemas; a `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `ANTIGRAVITY_*` / `GEMINI_*` / `GOOGLE_*` / `PI_*` / `GROK_*` / `XAI_*` / `DSH_*` / `DEEPSEEK_*` / `OMP_*` env-prefix allowlist gates which settings each CLI can receive, and the keys that could redirect a CLI's traffic (base URLs, config homes) are clamped for non-admin users
+- **Path containment** — file routes `realpath` before boundary checks (no TOCTOU); `..`, absolute paths, and symlinks resolving outside the working dir are rejected. Caps: 10 MB text preview / 2 GB raw & download (`CODEMAN_MAX_DOWNLOAD_BYTES`; bodies stream and answer `Range` requests, so the cap is a sanity bound rather than memory protection); `/api/download` blocklists sensitive paths (`.env`, `*credentials*`, `~/.ssh/`, `.aws/credentials`). SVG/HTML is served `octet-stream` + `nosniff` + attachment so it downloads rather than executes
 - **Security headers** — `Content-Security-Policy` (`default-src 'self'`, every exception enumerated), `X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`, HSTS over HTTPS, and CORS reflected **only** for `localhost` / `127.0.0.1` / `::1`
 
 ### Supply chain & isolation
@@ -625,17 +674,19 @@ These run for **every** request — before auth, even on the default no-password
 
 ---
 
-## SSH Alternative (`sc`)
+## Terminal UI (`codeman tui`)
 
-If you prefer SSH (Termius, Blink, etc.), the `sc` command is a thumb-friendly session chooser:
+A full-screen dashboard for your sessions, in the terminal. Same states as the web UI, because it is a client of the same server:
 
 ```bash
-sc              # Interactive chooser
-sc 2            # Quick attach to session 2
-sc -l           # List sessions
+codeman tui              # the dashboard
+codeman tui --list       # numbered session list, then exit (scriptable)
+codeman tui 2            # attach straight to session 2 of that list
 ```
 
-Single-digit selection (1-9), color-coded status, token counts, auto-refresh. Detach with `Ctrl+A D`.
+Sessions are grouped **NEEDS YOU → WORKING → IDLE → RECENT**, longest-waiting first. `↑↓`/`j`/`k` select, `1`-`9` and `[`/`]` switch between sessions, `Enter` attaches into the tmux pane (**`F1`** to come back). Inside a pane the bar across the top keeps the session strip visible and `Alt+1`-`Alt+9` switch without leaving. `y`/`n`/digit answer a pending permission dialog right from the list, `p` sends a one-line prompt, `n` starts a session and opens straight into it, `x` kills one (`y` confirms), `/` searches, `g` shows the away digest, `?` is help, `q` quits. Below 72 columns it drops the preview pane and becomes a single-column list, so it stays usable in Termius on a phone. With no server running it still starts in attach-only degraded mode.
+
+The web UI remains the primary surface; see **[docs/tui.md](docs/tui.md)** for the full guide.
 
 ---
 
@@ -650,13 +701,21 @@ Single-digit selection (1-9), color-coded status, token counts, auto-refresh. De
 | `Ctrl/Cmd+Tab`                  | Next session                                                  |
 | `Alt/Option+[` / `Alt/Option+]` | Previous / next session                                       |
 | `Alt/Option+1`-`Alt/Option+9`   | Switch to tab N (physical keys, so macOS Option layouts work) |
+| `Alt/Option+B`                  | Collapse / expand the session sidebar (sidebar layout only)   |
 | `Ctrl+Shift+{` / `Ctrl+Shift+}` | Move active tab left / right                                  |
+| `Ctrl/Cmd+C`                    | Copy selection, or interrupt when nothing is selected         |
+| `Ctrl+Shift+C`                  | Copy selection (never interrupts)                             |
+| `Ctrl/Cmd+V`                    | Paste, or upload a clipboard image and paste its path          |
 | `Ctrl/Cmd+L`                    | Clear terminal                                                |
 | `Ctrl+Shift+R`                  | Restore terminal size                                         |
 | `Ctrl+Shift+V`                  | Toggle voice input                                            |
 | `Ctrl/Cmd +` / `-`              | Font size                                                     |
 | `Ctrl/Cmd+?`                    | Keyboard help                                                 |
 | `Shift+Enter`                   | Insert newline (sent to terminal)                             |
+| `Shift+drag`                    | Select text in a pane whose mouse events go to the CLI        |
+| Right-click                     | Copy the selection (the native menu stays when nothing is selected) |
+| `Shift+Wheel`                   | Scroll the local scrollback while the wheel is forwarded to the CLI |
+| `Ctrl+Z`                        | Swallowed in agent sessions so a running CLI cannot be suspended; normal job control in a shell |
 | `Escape`                        | Close panels & modals                                         |
 
 ---
@@ -665,6 +724,79 @@ Single-digit selection (1-9), color-coded status, token counts, auto-refresh. De
 
 For AI agents and automation that control Codeman without a browser: an agent that spins up worker sessions, a CI bot, or **Claude Code running _inside_ a Codeman session orchestrating other sessions**. Everything the UI does is HTTP + a CLI, so an agent can do it too.
 
+### The agent skill (start here)
+
+Everything in this section also ships as a **Claude Code skill** in [`skills/codeman`](skills/codeman/SKILL.md). Install it once and you never paste API docs into a prompt again. You ask for what you want in plain English, and the agent already sitting inside a Codeman session loads the recipes and drives the API itself.
+
+#### Step 1: install it
+
+| How            | Command                                                    | Scope                                                                                      |
+| -------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Skills CLI     | `npx skills add Ark0N/Codeman --skill codeman -g`          | Global, works for any skills-aware agent                                                   |
+| Claude Code plugin | `/plugin marketplace add Ark0N/Codeman` then `/plugin install codeman@codeman` | Global, through Claude Code's plugin manager; `/plugin update codeman` follows releases. Pick this OR a `codeman skill install`, not both: a Claude Code with both lists the skill twice (`codeman` and `codeman:codeman`) |
+| Bundled CLI    | `codeman skill install`                                    | Global (`~/.claude/skills/codeman`), for npm installs that never cloned the repo            |
+| Bundled CLI    | `codeman skill install --case <name>`                      | One case only                                                                              |
+| Web UI         | App Settings → Agents & CLIs → Claude → **Agent Skill**    | Auto-injects into each case on Claude session create (`agentSkillEnabled`, SYNCED, default off) |
+
+`codeman skill uninstall [--case <name>]` reverses the CLI installs, and never touches a `skills/codeman` you wrote yourself.
+
+#### Step 2: ask for things
+
+That is the entire interface. No curl, no endpoint names, no session ids. These prompts work as written:
+
+| You say                                                                                    | The skill does                                                                                           |
+| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| _"What sessions are running right now?"_                                                   | Lists them with name, mode and status. Read-only, safe to ask anytime.                                    |
+| _"Start a shell worker on the `myapp` case, run the test suite, tell me if it passes."_    | Spawns, waits on a split completion marker, reads back the exit code, cleans up.                          |
+| _"Spin up 3 workers for lint, typecheck and tests. Run them in parallel, report failures."_ | The fan-out flow: one session per task, all started first, then gathered as each finishes.                |
+| _"Have a claude worker on `refactor-auth` summarize `src/session.ts`, then close it."_     | Spawns, runs the readiness ladder (first-run trust dialog included), send-and-wait, reads the clean transcript answer, deletes. |
+| _"Watch session w4 and tell me if it gets stuck on a permission prompt."_                  | Blocks on the `blocked` signal and surfaces the question to **you**. It never answers another session's prompt itself. |
+
+#### Step 3: nothing
+
+The agent deletes every session it started. Watch the tabs appear and disappear in the dashboard while it works.
+
+#### A real run, start to finish
+
+> **You:** spin up 3 shell workers, run lint / typecheck / the frontend syntax check in parallel, and tell me which failed.
+
+```text
+lint       -> 9f2d8e5f   dispatched
+typecheck  -> aff9c691   dispatched     3 tabs appear in the dashboard
+syntax     -> be9f1f15   dispatched
+
+lint         DONE_lint_17909      rc=0
+typecheck    DONE_typecheck_3409  rc=0   gathered as each one finishes
+syntax       DONE_syntax_18501    rc=0
+
+deleted 9f2d8e5f, aff9c691, be9f1f15    tabs disappear
+```
+
+Those `DONE_<task>_<random>` strings are the skill's **split marker** trick, and they are why the fan-out is reliable on hook-less `shell` sessions: the typed line contains `${M}_17909`, so only the command's real *output* ever contains `DONE_17909`. An unsplit marker would match the echo of your own keystrokes before the command had even run.
+
+#### What's in the box
+
+| File                                                                | Contents                                                                                    |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| [`SKILL.md`](skills/codeman/SKILL.md)                               | Safety rules, the ready-made fast path (spawn N workers, task them, collect), and the verb index. Always loaded. |
+| [`reference/verbs.md`](skills/codeman/reference/verbs.md)           | The 14 verbs in detail: readiness, send-and-wait, markers, interrupts, cleanup. On demand.   |
+| [`reference/recipes.md`](skills/codeman/reference/recipes.md)       | 8 worked flows: claude, DeepSeek Harness and shell workers, fan-out, blocked-worker watch, messaging fan-out. On demand. |
+| [`reference/endpoints.md`](skills/codeman/reference/endpoints.md)   | Full endpoint tables, error codes, per-mode signal table, capacity limits. On demand.        |
+| [`reference/messaging.md`](skills/codeman/reference/messaging.md)   | Talking to claude workers directly via Claude Code cross-session messaging. On demand.       |
+
+Every recipe in there was verified against a live server, and the comments record the failure modes that were measured rather than guessed.
+
+#### Two things worth knowing
+
+- **It self-gates.** Outside a Codeman session (`CODEMAN_MUX` unset) the skill refuses to act and does not guess an API URL, so a global install costs an unrelated Claude Code session nothing.
+- **It is deliberately conservative.** Unprompted, it may only spawn sessions, prompt them, and delete ones **it created in that same conversation, by exact id**, through a fail-closed guard that refuses to delete the agent's own session. Deleting a case (which erases a real directory of your code), bulk kills, respawn/ralph/cron/orchestrator changes and settings writes all require you to ask, naming the target.
+
+⚠️ Turning `agentSkillEnabled` back off **does not remove already-injected copies** (a create-time sweep would yank the skill out from under other live sessions sharing that `.claude/` dir). Remove them per case with `codeman skill uninstall --case <name>`.
+
+---
+
+**The rest of this section is the manual path**: the same operations as raw HTTP, for a CI bot, a shell script, or any agent without skill support.
+
 ### Detect that you're inside Codeman
 
 When a CLI runs in a Codeman-managed session, these environment variables are set — read them instead of hardcoding anything:
@@ -678,15 +810,21 @@ When a CLI runs in a Codeman-managed session, these environment variables are se
 
 ### Rules of the road (read before you POST)
 
-1. **Single-line input only.** Programmatic input is sent as literal text **+ Enter** in one shot. Multi-line strings break the agent TUI (Ink) — send one line, or split into multiple calls.
+1. **Single-line input, ending in `\r`.** Programmatic input is sent as literal text, and Enter fires **only when the input contains a carriage return**: `{"input":"run tests\r"}`. Without the `\r` the text sits on the session's prompt unsubmitted (and a combined `wait` runs its full timeout on a turn that never started). Embedded newlines are stripped rather than rejected, so `"echo A\necho B\r"` runs the joined command `echo Aecho B`: send one line per call.
 2. **Make input idempotent.** Include a stable `clientId` and a monotonic per-session `seq` on `POST …/input`. The server de-duplicates, so a retry after a dropped connection can't double-deliver a prompt.
-3. **Auth.** If `CODEMAN_PASSWORD` is set, send HTTP Basic auth (user `admin` or `CODEMAN_USERNAME`) or a `codeman_session` cookie. The default loopback install is passwordless. A missing `Origin` header is allowed, so plain `curl` works; cross-site browser origins are rejected (CSRF guard).
+3. **Auth.** If `CODEMAN_PASSWORD` is set, send HTTP Basic auth (user `admin` or `CODEMAN_USERNAME`) or a `codeman_session` cookie. The default loopback install is passwordless. A missing `Origin` header is allowed, so plain `curl` works; cross-site browser origins are rejected (CSRF guard). ⚠️ A `401` replies with the bare string `Unauthorized`, **not** the JSON envelope, so piping it into `jq` throws a parse error instead of showing the failure: check the status before parsing.
 4. **Response envelope.** Most endpoints return `{ "success": true, "data": … }` (errors: `{ "success": false, "error", "errorCode" }`). A few legacy GETs return bare bodies — **handle both** (`body.data ?? body`).
 5. **`/api/v1/*`** is a stable alias of `/api/*`.
+6. **Wait instead of polling, and don't treat a timeout as an error.** The wait endpoints answer with HTTP `200` and `wait.timedOut: true` when nothing happened in time, so loop over short waits (60s is the default) rather than issuing one long call, because tunnels cut idle connections. `wait.timeoutMs` tells you the timeout the server actually applied after clamping (600s ceiling).
+7. **Only `claude` and `deepseek` sessions emit `stop` and `blocked`.** Those two come from hooks (Claude Code's own, and the DeepSeek Harness status bridge); `shell` and the other external CLIs (opencode/codex/gemini/antigravity/pi/grok/omp) accept only `idle`, `working` and `exit`. Asking for `stop` explicitly on those is a `400`; omitting `until` is always safe. ⚠️ On a `shell` session `idle` fires **once**, at startup, and never again, so send-and-wait there can only time out; synchronize hook-less sessions with a `wait-output` marker.
+8. **Nothing reports "ready", so wait for it explicitly.** A new session answers `{"signal":"exit","immediate":true}` (that means *not started*, not *crashed*) until its PID exists, and a `claude` worker in a fresh case then sits on the CLI's trust dialog. Prompt it there and the wait resolves on `idle` in ~2s looking exactly like a finished turn, while the text sits stuck in the dialog. Recipe 2b below is the sequence that avoids it.
 
 ### Recipes
 
 ```bash
+# CODEMAN_API_URL is auto-set inside every Codeman session, correct scheme included.
+# The fallback below fits a stock install; on a --https install set the https:// URL
+# yourself and add -k to each curl (self-signed cert).
 API="${CODEMAN_API_URL:-http://127.0.0.1:3000}"
 # (add  -u admin:"$CODEMAN_PASSWORD"  to each call if a password is set)
 
@@ -698,18 +836,74 @@ curl -s -X POST "$API/api/quick-start" \
   -H 'Content-Type: application/json' \
   -d '{"caseName":"refactor-auth","mode":"claude","effort":"high"}' | jq
 
+# 2b. Wait until that worker is actually READY (see rule 8): composer marker first,
+#     first-run trust dialog only as the fallback. (Probing trust first and sending
+#     a blind Enter misfires on re-runs: the dialog text stays in the buffer forever,
+#     so the probe matches stale text and the Enter lands in a ready composer.)
+#     Match single tokens: TUI text can reach the matcher without its spaces.
+until [ "$(curl -s "$API/api/sessions/$SID" | jq '.data.pid')" != null ]; do sleep 1; done
+R=$(curl -sG "$API/api/sessions/$SID/wait-output" --data-urlencode 'match=bypass' \
+      --data-urlencode 'from=buffer' --data-urlencode 'timeout=5000')
+if ! jq -e '.data.wait.matched' <<<"$R" >/dev/null; then
+  T=$(curl -sG "$API/api/sessions/$SID/wait-output" --data-urlencode 'match=trust' \
+        --data-urlencode 'from=buffer' --data-urlencode 'timeout=2000')
+  jq -e '.data.wait.matched' <<<"$T" >/dev/null && \
+    curl -s -X POST "$API/api/sessions/$SID/input" -H 'Content-Type: application/json' \
+      -d '{"input":"\r","useMux":true}'        # accept the first-run trust dialog
+  curl -sG "$API/api/sessions/$SID/wait-output" --data-urlencode 'match=bypass' \
+    --data-urlencode 'from=buffer' --data-urlencode 'timeout=45000' >/dev/null
+fi
+
 # 3. Send a prompt into a session (exactly-once: clientId + seq)
 curl -s -X POST "$API/api/sessions/$SID/input" \
   -H 'Content-Type: application/json' \
-  -d '{"input":"Run the test suite and summarize failures","useMux":true,"clientId":"agent-1","seq":1}'
+  -d '{"input":"Run the test suite and summarize failures\r","useMux":true,"clientId":"agent-1","seq":1}'
 
-# 4. Read the terminal back
-curl -s "$API/api/sessions/$SID/output" | jq -r '.data // .'
+# 4. Send a prompt and BLOCK until that turn is done (registers the wait before
+#    writing, so it can't answer with the previous turn's idle state)
+curl -s -X POST "$API/api/sessions/$SID/input" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"Run the test suite and summarize failures\r","useMux":true,
+       "clientId":"agent-1","seq":2,"wait":"stop,exit","waitTimeout":60000}' \
+  | jq '.data.wait'      # -> {"signal":"stop","timedOut":false,"waitedMs":41230,...}
+#    (`stop` is the definitive end-of-turn hook. Adding `idle` makes it resolve on a
+#     spinner pause too, and on anything that redraws a ❯ prompt — like a dialog.)
 
-# 5. Stream live events (session output, agent activity, status)
+# 4b. Timed out? That's a 200, not a failure. Loop over short waits.
+curl -s "$API/api/sessions/$SID/wait?until=stop,exit&timeout=60000" | jq '.data.wait'
+
+# 4c. Or wait for a marker in the output (works for shell sessions too).
+#     ⚠️ Unique per call (tmux repaints replay old screen text), and SPLIT so the
+#     typed line never contains it: your own keystrokes echo into the output
+#     stream, so an unsplit marker matches before the command has run. from=buffer
+#     catches a marker that printed before the wait landed.
+N=$RANDOM
+curl -s -X POST "$API/api/sessions/$SID/input" -H 'Content-Type: application/json' \
+  -d "{\"input\":\"M=DONE; npm test; echo \${M}_$N rc=\$?\r\",\"useMux\":true}"
+curl -sG "$API/api/sessions/$SID/wait-output" \
+  --data-urlencode "match=DONE_$N" --data-urlencode 'from=buffer' \
+  --data-urlencode 'timeout=60000' | jq '.data.wait'
+
+# 5. Read the answer. claude / codex / deepseek sessions have last-response: it comes
+#    from the transcript, not the screen, so no TUI frames or repaint noise.
+#    ⚠️ Poll rather than read once: the transcript lands slightly after the stop
+#    signal, so a read right after send-and-wait returns often comes back empty.
+for _ in $(seq 1 10); do
+  TXT=$(curl -s "$API/api/sessions/$SID/last-response" | jq -r '.data.text')
+  [ -n "$TXT" ] && break; sleep 1
+done
+printf '%s\n' "$TXT"
+
+# 5b. Other modes (shell/opencode/gemini/antigravity/pi/grok/omp) have no transcript:
+#     read the terminal. ⚠️ Use terminal?tail=, NOT /output: the latter's textOutput
+#     is empty for every tmux-backed (i.e. every interactive) session. tail counts
+#     BYTES, and what comes back is terminal data, ANSI included.
+curl -s "$API/api/sessions/$SID/terminal?tail=8000" | jq -r '.data.terminalBuffer'
+
+# 6. Stream live events (session output, agent activity, status)
 curl -sN "$API/api/events"          # Server-Sent Events
 
-# 6. Schedule recurring work (cron-style job)
+# 7. Schedule recurring work (cron-style job)
 curl -s -X POST "$API/api/cron/jobs" \
   -H 'Content-Type: application/json' \
   -d '{"name":"nightly-deps","agentType":"claude","workingDir":"/home/me/proj",
@@ -717,11 +911,11 @@ curl -s -X POST "$API/api/cron/jobs" \
        "inputMode":"typed","scheduleType":"daily","dailyTime":"03:00",
        "enabled":true,"concurrencyPolicy":"warn_only"}' | jq
 
-# 7. Inspect background sub-agents and their transcripts
+# 8. Inspect background sub-agents and their transcripts
 curl -s "$API/api/subagents" | jq '.data // .'
 curl -s "$API/api/subagents/$AID/transcript" | jq -r '.data // .'
 
-# 8. Whole-system snapshot (sessions, settings, respawn, stats)
+# 9. Whole-system snapshot (sessions, settings, respawn, stats)
 curl -s "$API/api/status" | jq
 ```
 
@@ -734,7 +928,9 @@ codeman session start -d /path/to/repo   # (s)  start a session
 codeman session list                     #      list sessions
 codeman session logs <id>                #      tail output
 codeman task add "fix the failing test"  # (t)  queue a task
-codeman attach <path>                     #      attach a Claude hook context
+codeman attach <path>                    #      show an attachment card for a local file
+codeman tui --list                       #      numbered session list (plain text when piped)
+codeman tui 3                            #      attach to session 3 of that list
 ```
 
 ### Hooks (events flowing _back_ to Codeman)
@@ -747,7 +943,7 @@ Codeman registers Claude Code hooks that `POST /api/hook-event` (`permission_pro
 
 ## API
 
-REST over Fastify — **~190 handlers across 20 route modules**, plus an SSE stream and a WebSocket terminal channel. All responses use the `ApiResponse<T>` envelope (`{success, data}` / `{success, error, errorCode}`); `/api/v1/*` is a stable alias. A representative subset:
+REST over Fastify — **~230 handlers across 25 route modules**, plus an SSE stream and a WebSocket terminal channel. All responses use the `ApiResponse<T>` envelope (`{success, data}` / `{success, error, errorCode}`); `/api/v1/*` is a stable alias. A representative subset:
 
 ### Sessions
 
@@ -755,11 +951,16 @@ REST over Fastify — **~190 handlers across 20 route modules**, plus an SSE str
 | -------- | -------------------------- | ---------------------------------------------------------------------------------- |
 | `GET`    | `/api/sessions`            | List all                                                                           |
 | `POST`   | `/api/quick-start`         | Create case + start session (`{caseName?, mode?, effort?, envOverrides?}`)         |
-| `POST`   | `/api/sessions/:id/input`  | Send input (`{input, useMux?, clientId?, seq?}` — `clientId`+`seq` = exactly-once) |
-| `GET`    | `/api/sessions/:id/output` | Read terminal output                                                               |
+| `POST`   | `/api/sessions/:id/input`  | Send input (`{input, useMux?, clientId?, seq?, wait?, waitTimeout?}`: `clientId`+`seq` = exactly-once; `wait` blocks until the turn ends) |
+| `GET`    | `/api/sessions/:id/terminal` | Read terminal output (`?tail=<bytes>`, `?full=1`); the read path for interactive sessions |
+| `GET`    | `/api/sessions/:id/output` | Parsed one-shot output (`textOutput` is empty for tmux-backed sessions)             |
+| `GET`    | `/api/sessions/:id/last-response` | The last answer as clean text, read from the transcript (claude, codex, deepseek) |
+| `GET`    | `/api/sessions/:id/wait`   | Block until a signal fires (`?until=stop,idle,exit&timeout=&fresh=`); a timeout is a `200` |
+| `GET`    | `/api/sessions/:id/wait-output` | Block until a literal string appears (`?match=&nocase=&from=now\|buffer&timeout=`) |
 | `GET`    | `/api/sessions/unified`    | Unified live + history list (Session Manager) — `?q=&limit=`                       |
 | `POST`   | `/api/sessions/:id/pin`    | Pin/unpin in the Session Manager (`{pinned}`)                                      |
 | `PUT`    | `/api/session-order`       | Sync tab order across devices (`{order: [ids]}`)                                   |
+| `POST`   | `/api/sessions/:id/custom-model` | Restart the session's CLI on a saved custom endpoint (`{endpointId, modelId}`; `{clear: true}` returns to the native backend) |
 | `DELETE` | `/api/sessions/:id`        | Delete session                                                                     |
 
 ### Respawn
@@ -808,8 +1009,11 @@ REST over Fastify — **~190 handlers across 20 route modules**, plus an SSE str
 | `GET`  | `/api/system/update/check`      | Check for a new release                        |
 | `POST` | `/api/system/update`            | Self-update (git-clone installs)               |
 | `POST` | `/api/clipboard`                | Push text to all connected browsers (`{text}`) |
+| `GET` / `POST` | `/api/model-endpoints`  | List / save custom OpenAI-compatible endpoints (`PUT` / `DELETE` `/:id`; admin-only in multi-user mode) |
 | `GET`  | `/api/sessions/:id/run-summary` | Timeline + stats                               |
 
+> **Building something on top of Codeman?** [`docs/extending-codeman.md`](docs/extending-codeman.md) is the integration guide: render your own UI as a tab, subscribe to the SSE event stream to react when an agent needs you, drive Codeman from a script, and the traps worth knowing before you start. Codeman has no plugin runtime on purpose, so an integration is just your own process talking HTTP.
+
 ---
 
 ## Architecture
@@ -842,7 +1046,7 @@ flowchart TB
         end
 
         subgraph External["External"]
-            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Gemini</small>"]
+            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Antigravity / Gemini / Pi / Grok / DeepSeek / OMP</small>"]
             BG["Background Agents<br/><small>(Task tool)</small>"]
         end
     end
@@ -873,13 +1077,19 @@ flowchart TB
 npm install
 npx tsx src/index.ts web    # Dev mode
 npm run build               # Production build
-npm run test:ci             # Run tests (the CI suite; browser suites need extra setup)
+npm test                    # Run tests (same suite CI runs; browser/mobile/perf suites have their own commands)
 ```
 
 See [CLAUDE.md](./CLAUDE.md) for full documentation.
 
 ---
 
+## Community
+
+Questions, setup help, and ideas live in [GitHub Discussions](https://github.com/Ark0N/Codeman/discussions): the [Q&A section](https://github.com/Ark0N/Codeman/discussions/categories/q-a) answers the most common ones (phone access, overnight runs, updating), and the roadmap gets decided in [Ideas](https://github.com/Ark0N/Codeman/discussions/categories/ideas). Bugs go to [issues](https://github.com/Ark0N/Codeman/issues); reports usually get a response within a day, and every release credits its reporters and contributors by name. Want to contribute? [CONTRIBUTING.md](.github/CONTRIBUTING.md) has the map: skins, translations, and docs make great first PRs, and bigger features start life as a Discussion. And if you're proud of your rig, post it in [Show and tell](https://github.com/Ark0N/Codeman/discussions/300).
+
+---
+
 ## Codebase Quality
 
 The codebase went through a comprehensive 7-phase refactoring that eliminated god objects, centralized configuration, and established modular architecture:
@@ -903,7 +1113,7 @@ Full details: [`docs/archive/code-structure-findings.md`](docs/archive/code-stru
 
 [![npm](https://img.shields.io/npm/v/xterm-zerolag-input?style=flat-square&color=22c55e)](https://www.npmjs.com/package/xterm-zerolag-input)
 
-Instant keystroke feedback overlay for xterm.js. Eliminates perceived input latency over high-RTT connections by rendering typed characters immediately as a pixel-perfect DOM overlay. Zero dependencies, 6.1 kB gzipped, configurable prompt detection, CJK/emoji wide-character support, full state machine with 175 tests.
+Instant keystroke feedback overlay for xterm.js. Eliminates perceived input latency over high-RTT connections by rendering typed characters immediately as a pixel-perfect DOM overlay. Zero dependencies, 6.1 kB gzipped, configurable prompt detection, CJK/emoji wide-character support, full state machine with 238 tests.
 
 ```bash
 npm install xterm-zerolag-input

README.zh-CN.md

@@ -5,7 +5,7 @@
 <h2 align="center">AI 编程智能体的任务控制中心</h2>
 
 <p align="center">
-  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Gemini &bull; 终端 —— 统一仪表盘 &bull; 任意设备</em>
+  <em>Claude Code &bull; OpenCode &bull; Codex &bull; Antigravity &bull; Gemini &bull; Pi &bull; Grok &bull; DeepSeek &bull; OMP &bull; 终端 —— 统一仪表盘 &bull; 任意设备</em>
 </p>
 
 <p align="center">
@@ -17,20 +17,24 @@
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%2B-22c55e?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 22+"></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9-3b82f6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.9"></a>
   <a href="https://fastify.dev/"><img src="https://img.shields.io/badge/Fastify-5.x-1e3a5f?style=flat-square&logo=fastify&logoColor=white" alt="Fastify"></a>
+  <a href="https://www.npmjs.com/package/aicodeman"><img src="https://img.shields.io/npm/v/aicodeman?style=flat-square&label=npm&color=22c55e" alt="npm version"></a>
+  <a href="https://github.com/Ark0N/Codeman/stargazers"><img src="https://img.shields.io/github/stars/Ark0N/Codeman?style=flat-square&color=eab308" alt="GitHub stars"></a>
   <a href="https://github.com/Ark0N/Codeman/graphs/contributors"><img src="https://img.shields.io/github/contributors/Ark0N/Codeman?style=flat-square&color=3b82f6" alt="Contributors"></a>
   <a href="https://github.com/Ark0N/Codeman/commits/master"><img src="https://img.shields.io/github/commit-activity/t/Ark0N/Codeman?style=flat-square&color=1e3a5f" alt="Total commits"></a>
 </p>
 
+<p align="center">
+  ⭐ <strong>喜欢 Codeman？<a href="https://github.com/Ark0N/Codeman">在 GitHub 上给它点个 Star 吧！</a></strong>只需轻点一下，就能帮助更多人发现这个项目。⭐
+</p>
+
 <p align="center">
   <img src="docs/images/subagent-demo-20260724.gif" alt="Codeman — 并行子智能体可视化" width="900">
 </p>
 
-<p align="center">
-  <img src="docs/images/codeman-tour-20260724.png" alt="Codeman 仪表盘导览：按项目分组的会话标签页、一键 Run 启动新智能体、页头实时用量" width="900">
-</p>
-
 > 本文档由英文版 [`README.md`](README.md) 翻译而来。如有出入，以英文版为准。
 
+**Codeman** 是一个自托管的 AI 编程智能体任务控制中心。它在持久化的 tmux 会话里拉起 Claude Code、OpenCode、Codex、Antigravity、Gemini、Pi、Grok、DeepSeek Harness 或 OMP，把真实的终端流式传到任意浏览器，并在你离开之后让智能体继续干活：空闲时重新提示、用量限额重置后自动续跑、按计划执行任务，还能实时展示每一个后台智能体的工作。
+
 一行命令即可安装（macOS 和 Linux，Windows 通过 WSL）：
 
 ```bash
@@ -44,6 +48,17 @@ codeman web
 
 安装器在每次系统改动前都会先询问；重跑同一条命令即可原地更新。详见[快速开始 — 安装](#快速开始--安装)。
 
+- **一个仪表盘，九个 CLI**：每个会话可选 [Claude Code、OpenCode、Codex、Antigravity、Gemini、Pi、Grok、DeepSeek 或 OMP](#更多特性)（外加普通 shell），在本机、[Docker 容器](#隔离的-docker-会话)或 [SSH 远程主机](#远程-ssh-会话)上运行，你自己的仪表盘也能作为 [Web 标签页](#更多特性)并排打开
+- **真正的手机友好**：[触控优化的终端](#移动端优化的-web-ui)，即时本地回显、二维码登录、滑动导航与推送通知
+- **睡觉时也在跑**：[空闲检测 + 重生循环](#重生控制器respawn-controller)，订阅限额重置后自动续跑，支持 24 小时以上的无人值守运行
+- **看见智能体在想什么**：每个子智能体和团队成员都有[实时浮动窗口](#实时智能体可视化)，附带实时活动记录
+- **什么都不会丢**：tmux 让会话挺过重启和断网，输入精确一次送达，完整的回滚缓冲区回放
+- **自托管、私有**：默认仅环回、MIT 许可、无遥测，完全运行在你自己的机器上
+
+<p align="center">
+  <img src="docs/images/codeman-tour-20260724.png" alt="Codeman 仪表盘导览：按项目分组的会话标签页、一键 Run 启动新智能体、页头实时用量" width="900">
+</p>
+
 ---
 
 ## 快速开始 — 安装
@@ -52,13 +67,14 @@ codeman web
 curl -fsSL https://getcodeman.com/install | bash
 ```
 
-该脚本会在缺失时自动安装 Node.js 和 tmux，把 Codeman 克隆到 `~/.codeman/app` 并完成构建。几点须知：
+该脚本会在缺失时自动安装 Node.js、tmux 和一套构建工具链（node-pty 没有 Linux 预编译包，需要从源码编译），把 Codeman 克隆到 `~/.codeman/app` 并完成构建。几点须知：
 
 - **先询问，后改动。** 所有系统级改动（安装软件包、下载 AI CLI）都会先征求确认；结束时的菜单可选择：直接在本终端运行、安装为后台服务（systemd/launchd，开机自启），或暂不启动。不选就不会有任何后台进程。
+- **怎么访问，由你决定。** 安装器提供三种到达仪表盘的方式：**Tailscale**（环回绑定，由 `tailscale serve` 代理，得到带真实证书的 `https://<机器名>.<tailnet>.ts.net`，用你的 tailnet 当登录，无需密码）、**局域网内任意设备**（`0.0.0.0`，会提示设置一个强烈推荐的密码），或**仅本机**（`127.0.0.1`，最安全）。绑定网络却跳过密码需要显式确认，并以醒目警告收尾。高亮的默认项反映机器上已有的状态（已在用 Tailscale 时默认 Tailscale，重跑时沿用现有绑定），直接回车绝不会引入新软件。手动运行的 `codeman web` 仍默认仅环回。
 - **重跑即更新。** 再次运行同一条命令即可原地更新已完成的安装：`~/.codeman/app` 中的本地改动会被 stash（绝不丢弃），运行中的服务会自动重启并校验。若首次安装中途失败，重跑会继续完成完整的安装流程。也可以使用 `install.sh update` 与 `install.sh uninstall`。
 - **CI / 无终端环境：** 没有终端时，涉及系统改动的步骤会带着说明中止，而不是静默执行；在自动化场景设置 `CODEMAN_NONINTERACTIVE=1` 即可批准这些步骤。
 
-你至少需要安装一个 AI 编程 CLI —— [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli) 或 [Gemini CLI](https://github.com/google-gemini/gemini-cli)（任意组合均可）。安装器会自动检测这四个中已安装的任意一个；若一个都没有，会提供安装 Claude Code 或 OpenCode 的选项，也可以选择跳过、稍后自行安装。安装完成后：
+你至少需要安装一个 AI 编程 CLI —— [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli)、[Antigravity](https://antigravity.google)、[Gemini CLI](https://github.com/google-gemini/gemini-cli)、[Pi](https://pi.dev)、[Grok Build](https://github.com/xai-org/grok-build)、[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 或 [OMP](https://github.com/can1357/oh-my-pi)（任意组合均可；自 Google 面向消费者停售后，Gemini CLI 仅限企业版，Antigravity 是其继任者）。安装器会自动检测这九个中已安装的任意一个；若一个都没有，会给出一个菜单让你安装其中任意一个（DeepSeek 除外，它的 npm 包只装一个启动器，没有可运行的 profile），也可以选择跳过、稍后自行安装。安装完成后：
 
 ```bash
 codeman web
@@ -72,12 +88,34 @@ codeman users add alice --admin      # 创建第一个管理员账号
 codeman web --multiuser              # 命名登录 + 按用户隔离的案例空间
 ```
 
+**更喜欢 Docker Compose？** `docker/` 里附带一套本地镜像的 Compose 部署：把 `docker/.env.example` 复制为 `docker/.env`，设置 `CODEMAN_PASSWORD`，然后在 Linux 上运行 `bash docker/Start-Codeman.sh`。Codeman 自己跑在容器里，并通过宿主机的 socket 把 Docker 案例作为并列容器拉起。更新之后请再跑一次这个脚本，而不是直接 `docker compose up`，这样重建的镜像、刷新的卷和新的入口脚本会一起就位。直接的 Compose 命令、存储与网络选项见 [Docker 部署指南](docker/README.md)（英文）。
+
 详见下文[多用户模式](#多用户模式可选启用)。
 
 <details>
-<summary><strong>作为后台服务运行</strong></summary>
+<summary><strong>让它在后台一直运行</strong></summary>
 
-安装器结尾的菜单（选项 2）可以帮你完成这一步，并在宣告成功前校验服务确实已启动。如需手动配置：
+想让它活过你启动它的那个 shell，而且什么都不用配置：
+
+```bash
+codeman web -d          # 脱离终端；日志写到 ~/.codeman/web.log
+codeman web --status    # 是否在运行，pid 是多少
+codeman web --stop      # 优雅的 SIGTERM；智能体继续留在 tmux 里运行
+```
+
+`-d` 会等到服务器真正应答后才报告成功，并且拒绝在同一个数据目录上启动第二个（两个服务器共用一个 tmux socket 会互相附着对方的会话）。
+
+想让它在重启后自动回来，就装成服务。安装器结尾的菜单（选项 2）会替你完成；`codeman service` 是 `npm i -g aicodeman` 安装的等价物：
+
+```bash
+codeman service install     # systemd 用户单元（Linux）或 LaunchAgent（macOS）
+codeman service status
+codeman service uninstall
+```
+
+`service install` 会把你当前的 PATH 写进单元文件，这比听起来重要得多：launchd 只给任务 `/usr/bin:/bin:/usr/sbin:/sbin`，所以手写的 plist 根本找不到 Homebrew 或 nvm 装的 `node`、`tmux` 或 `claude`。它绝不会把 `CODEMAN_PASSWORD` 复制进单元文件；服务需要认证的话请自行添加。
+
+如需手动编写单元文件：
 
 **Linux（systemd）：**
 
@@ -141,7 +179,7 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
 wsl bash -c "curl -fsSL https://getcodeman.com/install | bash"
 ```
 
-Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。如果还没装 WSL：在管理员 PowerShell 中运行 `wsl --install`，重启，打开 Ubuntu，然后在 WSL 内安装你偏好的 AI 编程 CLI（[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli) 或 [Gemini CLI](https://github.com/google-gemini/gemini-cli)）。安装完成后，即可从 Windows 浏览器访问 `http://localhost:3000`。
+Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)。如果还没装 WSL：在管理员 PowerShell 中运行 `wsl --install`，重启，打开 Ubuntu，然后在 WSL 内安装你偏好的 AI 编程 CLI（[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[OpenCode](https://opencode.ai)、[Codex](https://developers.openai.com/codex/cli)、[Antigravity](https://antigravity.google)、[Gemini CLI](https://github.com/google-gemini/gemini-cli)、[Pi](https://pi.dev)、[Grok Build](https://github.com/xai-org/grok-build)、[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 或 [OMP](https://github.com/can1357/oh-my-pi)）。安装完成后，即可从 Windows 浏览器访问 `http://localhost:3000`。
 
 </details>
 
@@ -177,17 +215,17 @@ Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.
 <tr><td>在手机上手打密码</td><td><b>扫二维码 —— 即时认证</b></td></tr>
 </table>
 
-- **键盘配件栏** —— 在虚拟键盘上方提供 `/init`、`/clear`、`/compact` 快捷按钮；破坏性命令需双击确认，绝不误触
+- **键盘配件栏** —— 在虚拟键盘上方提供 `/init`、`/clear`、`/compact` 快捷按钮；破坏性命令需双击确认，绝不误触；在 Codex 会话上还会显示 `⇧←` / `⇧→`（Shift+Left / Shift+Right：编辑上一条排队的消息 / 在提示栈里回退）
 - **独立的 Enter 按钮** —— 以按键方式回放，先冲刷本地回显缓冲的文本，不会让内容滞留在屏幕上
 - **滑动导航与智能键盘处理** —— 左右滑动切换会话；键盘弹出时工具栏与终端整体上移（`visualViewport` API）
-- **为手机而生** —— 刘海与 Home 指示条的安全区适配、44px 触控目标、底部抽屉式 case 选择器、原生惯性滚动
+- **为手机而生** —— 刘海与 Home 指示条的安全区适配、44px 触控目标、底部抽屉式 case 选择器、原生惯性滚动；折叠屏手机（iPhone Duo）上对话框会避开铰链，开合设备也绝不会被误判成键盘弹出
 
 ```bash
 codeman web --https
 # 在手机上打开：https://<你的IP>:3000
 ```
 
-> `localhost` 走纯 HTTP 即可。从其他设备访问时请使用 `--https`，或使用 [Tailscale](https://tailscale.com/)（推荐）—— 它提供私有网络，让你无需 TLS 证书即可从手机访问 `http://<tailscale-ip>:3000`。
+> `localhost` 走纯 HTTP 即可。从其他设备访问时请使用 `--https`，或使用 [Tailscale](https://tailscale.com/)（推荐）：安装器可以替你配好（在网络访问提示处选择 **Tailscale**，或在已有安装上运行 `bash ~/.codeman/app/install.sh tailscale`）。这样你会得到带真实证书的 `https://<你的机器>.<tailnet>.ts.net`：只对你的 tailnet 可见、无需密码，手机上的 PWA 安装和推送通知也都能用。
 
 ### 安全的二维码认证
 
@@ -210,6 +248,8 @@ codeman web                       # localhost:3000（仅环回 —— 安全默
 codeman web --port 8080           # 自定义端口（或设置 CODEMAN_PORT）
 codeman web --https               # 自签名 TLS（仅远程访问时需要）
 codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_PASSWORD（见「安全」）
+codeman web -d                    # 脱离终端：关掉 shell 也在跑（--status、--stop）
+codeman service install           # systemd/launchd 服务：重启后自动回来
 ```
 
 打开打印出的 URL。整个页面是一个单一仪表盘；下面的一切都在这里完成。
@@ -220,16 +260,16 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_
 
 | 字段                   | 作用                                                                                        |
 | ---------------------- | ------------------------------------------------------------------------------------------- |
-| **工作目录 / case**    | 智能体操作的文件夹。「case」就是一个 Codeman 记住的命名工作目录。                           |
-| **CLI / 运行模式**     | `Claude`（默认）、`OpenCode`、`Codex`、`Gemini` 或 `Terminal`（普通 shell）。               |
-| **模型**               | 每会话模型（App Settings → Claude Model）。软默认值 —— 会话内 `/model` 依然有效。           |
+| **工作目录 / case**    | 智能体操作的文件夹。「case」就是一个 Codeman 记住的命名工作目录。**Add Case** 可以从零创建、链接一个已有文件夹，或把一个 GitHub 仓库直接克隆成 case（**Clone Repo**）。 |
+| **CLI / 运行模式**     | `Claude`（默认）、`OpenCode`、`Codex`、`Antigravity`、`Gemini`、`Pi`、`Grok`、`DeepSeek`、`OMP` 或 `Terminal`（普通 shell）。 |
+| **模型**               | 每会话模型（App Settings → Models → New Claude sessions）。软默认值 —— 会话内 `/model` 依然有效。 |
 | **Effort / Ultracode** | 推理力度（`low`–`max`），或用 `ultracode` 开启动态多智能体工作流。随时可用 `/effort` 切换。 |
 
 点击启动 —— Codeman 通过真实 PTY 拉起 CLI，并经 SSE 流式传输到你的浏览器。
 
 ### 3. 读懂仪表盘
 
-- **标签（顶部）** —— 每个会话一个。`Alt+1`–`9` 跳转，`Ctrl+Tab` 下一个，拖拽排序（标签顺序会跨设备同步）。
+- **标签（顶部）** —— 每个会话一个。`Alt+1`–`9` 跳转，`Ctrl+Tab` 下一个，拖拽排序（标签顺序会跨设备同步）。更喜欢列表？**App Settings → Appearance → Tabs** 可以把它挪进左侧边栏（带筛选框，`Alt+B` 折叠）或一条竖向导轨，导轨的行按活动状态排序：先是等你处理的，然后是跑得最久的，最后是刚刚安静下来的。
 - **终端（中央）** —— 真实的 `xterm.js` 终端；完整 TUI 正常渲染。直接输入并按 **Enter** 发送。`Shift+Enter` 插入换行。
 - **侧边面板** —— Respawn、Orchestrator、Cron、Subagents、Settings（从工具栏切换）。
 
@@ -237,8 +277,10 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_
 
 - **直接在终端输入提示** —— 即使跨越重连，输入也是精确一次送达（连接中断绝不会丢失或重复发送提示）。
 - **粘贴或拖放图片**，直接进入会话。
-- **语音输入** —— `Ctrl+Shift+V`（Deepgram Nova-3，自动静音停止）。
-- **附件** —— 注册外部文件/文档，并内联预览 Office/PDF。
+- **语音输入** —— `Ctrl+Shift+V`（Deepgram Nova-3，或者直接用这台机器的 Claude Code 登录、不需要任何 API key；自动静音停止）。
+- **附件** —— 注册外部文件/文档，并内联预览 Office/PDF；智能体打印出的任何文件路径都可以点击，终端里和对话视图里都行。
+- **需要你的时候** —— 标签会变黄（等待输入）或变红（有个问题挡住了它）。**审批收件箱（Approvals Inbox）**（可选启用）把所有会话里等着你的提示排成一个队列，可以从页头的铃铛或手机首页直接作答；🧠 **Read My Mind**（可选启用）会根据这个 case 的目标和最近的工作替你起草下一条提示。
+- **看到什么就能复制什么** —— `Shift+拖动` 在 CLI 接管了鼠标时也能选中文本，右键复制选中内容，自动复制（Auto Copy，可选启用）在松开鼠标的瞬间就复制。
 
 ### 5. 让它自主运行
 
@@ -246,19 +288,20 @@ codeman web -H 0.0.0.0            # 绑定局域网 —— 必须设置 CODEMAN_
 | ---------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
 | **Respawn**      | 长时间无人值守运行 —— 空闲/限额时自动重启 CLI，带自适应时序。预设：`solo-work`、`overnight-autonomous` 等 | Respawn 标签页                                                     |
 | **Orchestrator** | 把一个目标变成分阶段计划，并跨多个智能体推动完成。                                                        | 编排器面板                                                         |
-| **Cron**         | 已保存的、命名的定时任务（`once`/`interval`/`daily`/`weekly`），到期时拉起会话并发送提示。                | ⏰ Cron 按钮（可选启用：App Settings → Display → Header Displays） |
+| **Cron**         | 已保存的、命名的定时任务（`once`/`interval`/`daily`/`weekly`），到期时拉起会话并发送提示。                | ⏰ Cron 按钮（可选启用：App Settings → Header & Panels → Scheduling） |
 | **Auto-resume**  | 订阅限额重置后自动继续。                                                                                  | Respawn 标签页（顶部）                                             |
 
 ### 6. 随时随地访问
 
 - **手机/平板** —— UI 完全触控优化；扫描桌面上的**二维码**即可免密码登录。
 - **网络之外** —— `./scripts/tunnel.sh start` 打开一条 Cloudflare 隧道（先设置 `CODEMAN_PASSWORD`）。
-- **SSH** —— `sc` 选择器可从终端附着任意会话（`sc` 交互式，`sc 2` 快速附着，`sc -l` 列表）。
+- **SSH** —— `codeman tui` 是终端里的全屏会话面板（`codeman tui --list` 列出，`codeman tui 2` 直接附着到某个会话）。
 
 ### 7. 运维与维护
 
-- **App Settings** —— 模型、effort、权限启动模式、主题/皮肤、通知、显示开关、各 CLI 的专属选项，以及跨设备同步的自定义显示名称和按设备保存的英文/简体中文界面语言。
-- **自更新** —— git-clone 安装可在 **Settings → Updates** 中原地更新。
+- **App Settings** —— 模型、effort、权限启动模式、主题/皮肤、终端字体与字重、入场动画、通知、显示开关、各 CLI 的专属选项，以及跨设备同步的自定义显示名称和按设备保存的英文/简体中文界面语言。
+- **让它在后台运行** —— `codeman web -d` 脱离你的 shell（`--status`、`--stop`）；`codeman service install` 把它装成 systemd 用户单元 / macOS LaunchAgent，重启后自动回来。两者都会先确认服务器真正应答再报告成功，也都拒绝在同一个数据目录上启动第二个服务器。见[让它在后台一直运行](#快速开始--安装)。
+- **自更新** —— git-clone 安装可在 **App Settings → System → Updates** 中原地更新。
 - **部署你自己的改动** —— 见[开发](#开发)。
 
 > ⚠️ **安全提示：** 如果你正在 Codeman 受管会话*内部*工作（`echo $CODEMAN_MUX` → `1`），绝不要直接运行 `tmux kill-session` / `pkill claude` —— 请使用 Web UI 或 `./scripts/tmux-manager.sh`。
@@ -373,6 +416,14 @@ codeman web --title-hostname dev-box       # codeman:dev-box（用于覆盖嘈
 | **110k tokens** | 自动 `/compact` | 上下文被摘要，工作继续 |
 | **140k tokens** | 自动 `/clear`   | 以 `/init` 全新开始    |
 
+### 标签提醒（Tab Alerts）
+
+<p align="center">
+  <img src="docs/images/tab-alerts-glow-20260815.gif" alt="会话标签：一个普通的活动标签，旁边是黄色的等待输入标签和红色的需要决定标签，都带着呼吸式光晕" width="900">
+</p>
+
+每个标签一眼就能看出状态。运行中的会话保持绿色状态点。会话停下来等待输入时，标签变**黄**：稳定的描边、着色的背景、黄色的点，上面叠一层缓慢的呼吸光晕。当权限提示或提问**挡住**了智能体，标签变**红**，脉动更快。底色永远不会闪灭，所以哪怕只瞥一眼（或截一张图）也能读到真实状态；标签被选中时描边依然可见，页面刷新后会从服务端重新装载待处理的提醒，因此一个被挡住的会话绝不可能藏在一个看起来正常的标签后面。
+
 ### 通知
 
 当会话需要关注时实时桌面提醒 —— `permission_prompt` 与 `elicitation_dialog` 触发关键的红色标签闪烁，`idle_prompt` 触发黄色闪烁。点击任意通知即可直接跳转到相关会话。Hook 按 case 目录自动配置。
@@ -393,17 +444,24 @@ PTY 输出 → 16ms 服务端批处理 → DEC 2026 包裹 → SSE → 客户端
 
 ## 更多特性
 
-- **自更新** —— systemd/launchd 管理下的 git-clone 安装可在 **App Settings → Updates** 中原地更新：它会检测最新发行版，自动暂存（stash）脏工作树，并在服务重启期间流式展示构建进度（npm 安装会被报告为不可更新）
-- **多 CLI** —— 每个会话可选 **Claude Code**、**OpenCode**、**Codex** 或 **Gemini**；环境变量前缀自动隔离（`CLAUDE_CODE_*`、`OPENCODE_*`、`CODEX_*` 与 `GEMINI_*`/`GOOGLE_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md)
-- **Docker 会话** —— 在隔离且加固的容器中运行案例。**Create New** 上勾选一个复选框即可用合理的默认值启动容器并在其中启动智能体；同一案例的多个会话共享一个容器；可将容器连同工作区导出为可移植的 `.tar.gz`，迁移到另一台机器。详见 [`docs/docker-cases.md`](docs/docker-cases.md)
-- **远程 SSH 会话**：把案例指向另一台机器，让智能体在那里一个持久的远程 tmux 中运行：SSH 断连不中断任务、自动重连，还能发现并附着主机上已在运行的会话。详见 [`docs/remote-sessions.md`](docs/remote-sessions.md)
+- **后台守护进程与服务安装** —— `codeman web -d` 以脱离终端的方式运行服务器，带 pid 文件、`~/.codeman/web.log` 和经过校验的启动（它会轮询到服务器应答为止，所以端口冲突绝不会被当成成功）；`codeman service install` 写入一个 systemd 用户单元（Linux）或 LaunchAgent（macOS），并把你 shell 的 PATH 一并写进去，这样 nvm 或 Homebrew 装的 `node`、`tmux` 和 `claude` 才真的找得到。机密永远不会写进单元文件
+- **自更新** —— systemd/launchd 管理下的 git-clone 安装可在 **App Settings → System → Updates** 中原地更新：它会检测最新发行版，自动暂存（stash）脏工作树，并在服务重启期间流式展示构建进度（npm 安装会被报告为不可更新）
+- **把 GitHub 仓库克隆成 case** —— 在 **Add Case → Clone Repo** 里粘贴一个仓库 URL，Codeman 会把它克隆到 `~/codeman-cases/<name>` 并注册为普通 case，随时可以跑智能体。输入时它会预检 URL（告诉你能否匿名克隆，并为可选的分支/标签字段提供仓库真实的分支与标签），从 URL 里填好 case 名，还让你选 Run 按钮该用哪个 CLI。支持 `https://` 的公开仓库；Codeman 绝不收集或保存凭据
+- **多 CLI** —— 每个会话可选 **Claude Code**、**OpenCode**、**Codex**、**Antigravity**、**Gemini**、**Pi**、**Grok**、**DeepSeek Harness** 或 **OMP**；环境变量前缀自动隔离（`CLAUDE_CODE_*`、`OPENCODE_*`、`CODEX_*`、`ANTIGRAVITY_*`、`GEMINI_*`/`GOOGLE_*`、`PI_*`、`GROK_*`/`XAI_*`、`DSH_*`/`DEEPSEEK_*` 与 `OMP_*`）。详见 [`docs/opencode-integration.md`](docs/opencode-integration.md)、[`docs/pi-integration.md`](docs/pi-integration.md)、[`docs/grok-integration.md`](docs/grok-integration.md)、[`docs/deepseek-integration.md`](docs/deepseek-integration.md) 与 [`docs/omp-integration.md`](docs/omp-integration.md)
+- **自定义模型端点**（1.29.0 新增，目前仅 HTTP API）—— 让某个会话的 CLI 指向任意 OpenAI 兼容端点，而不是它自己的官方后端：本地的 llama.cpp、llama-swap、Ollama 或 vLLM 机器，也可以是 Azure AI Foundry、OpenRouter 这类云端网关。端点只需保存一次（`POST /api/model-endpoints`，模型列表从它的 `/v1/models` 自动发现），再应用到会话（`POST /api/sessions/:id/custom-model`），CLI 就会在原地重启并接上该端点。Claude、OpenCode、Pi、Grok 与 OMP 已实测通过；Codex、Gemini 与 DeepSeek 存在已记录的缺口，Antigravity 没有可用机制。工具栏选择器是下一步。详见 [`docs/custom-model-endpoints.md`](docs/custom-model-endpoints.md)
+- **Web 标签页** —— 把 Grafana、Uptime Kuma、一个 Vite 开发服务器或任何仪表盘 URL 作为标签页打开在会话旁边（Run 下拉菜单 → **Web / URL** → **Add URL**）。仪表盘通过 Codeman 自己的源代理，因此 `http://` 目标在手机上走 HTTPS 也能用、走隧道也能用；单页应用能在自己的路径上正常路由，页面自己重载后也能自行恢复。智能体打印出的 `localhost` 链接会自动以 Web 标签页打开。详见 [`docs/web-tabs.md`](docs/web-tabs.md)
+- **Docker 会话** —— 在隔离且加固的容器中运行 case。**Create New** 上勾选一个复选框即可用合理的默认值启动容器并在其中启动智能体；同一 case 的多个会话共享一个容器，也可以把 case 挂到你已经在跑的容器上；可将容器连同工作区导出为可移植的 `.tar.gz`，迁移到另一台机器。详见 [`docs/docker-cases.md`](docs/docker-cases.md)
+- **远程 SSH 会话** —— 把 case 指向另一台机器，让智能体在那里一个持久的远程 tmux 中运行：SSH 断连不中断任务、自动重连，还能发现并附着主机上已在运行的会话；文件预览与下载走同一条 ssh 连接。详见 [`docs/remote-sessions.md`](docs/remote-sessions.md)
 - **Effort 与 Ultracode** —— 设置每会话的默认 effort（`low`–`max`），或启用 **ultracode**（动态多智能体工作流）。这些都只是软默认值 —— 会话中可随时用 `/effort` 切换。扩展思考预算也可配置
-- **语音输入** —— 用 Deepgram Nova-3 口述提示（带 Web Speech API 回退）：切换录音、自动静音停止、实时音量表（`Ctrl+Shift+V`）
+- **语音输入** —— 用 Deepgram Nova-3 口述提示，或者干脆用这台机器的 Claude Code 登录、不需要任何 API key（App Settings → Voice；带 Web Speech API 回退）：切换录音、自动静音停止、实时音量表（`Ctrl+Shift+V`）
 - **图像输入** —— 直接把图片粘贴或拖放进会话
-- **手势控制** _(可选)_ —— 一个 MediaPipe 手部追踪叠加层，可徒手抓取/拖动会话窗口并捏合按钮。用 `CODEMAN_GESTURE=1` + App Settings → Display 启用
+- **手势控制** _(可选)_ —— 一个 MediaPipe 手部追踪叠加层，可徒手抓取/拖动会话窗口并捏合按钮。用 `CODEMAN_GESTURE=1` + App Settings → Terminal & Input 启用
 - **多显示器横跨** _(macOS)_ —— 一键打开一个横跨所有显示器最大化的浏览器窗口，让浮动的智能体/手势面板可以跨越物理拼接缝
-- **文件查看器按钮** _(可选)_ —— 头部新增一个按钮，一键切换内置文件浏览器面板；在 App Settings → Display → Header Displays 中启用
-- **CJK / 输入法支持** —— 完整支持中文 / 日文 / 韩文的组合输入
+- **文件查看器按钮** _(可选)_ —— 页头新增一个按钮，一键切换内置文件浏览器面板；在 App Settings → Header & Panels → Header buttons 中启用
+- **CJK / 输入法支持** —— 完整支持中文 / 日文 / 韩文的组合输入，Ctrl、Alt 修饰的导航键也会原样透传给 CLI
+- **页头里的套餐用量** —— 页头实时显示 Claude 订阅用量（5 小时窗口与每周窗口），数据来自 Codeman 在拉起 `claude` 时临时交给它的 statusline 导出器，绝不会写进你的设置文件；Codex 的限额则来自它自己的 app-server。按设备生效：桌面默认开，手机默认关
+- **会话列表，随你摆** —— 页头横条、带筛选框的左侧边栏，或一条竖向导轨，导轨的详细行带有创建时间与状态时长并按活动状态排序；手机首页和桌面首页导轨用的是同一套顺序
+- **终端外观** —— 七套皮肤（其中四套浅色）、按设备保存的字体与字重（内置的 JetBrains Mono 覆盖 100 到 800 的字重），以及可选启用的入场动画，覆盖标签、智能体窗口、终端面板和连接线
 - **操作系统通知与主机名感知标题** —— 桌面提醒与标签标题以 `codeman:<host>` 为前缀，使多主机配置不再含糊
 
 ---
@@ -416,7 +474,8 @@ PTY 输出 → 16ms 服务端批处理 → DEC 2026 包裹 → SSE → 客户端
 - **资源模板** —— 展开复选框可选 **Small / Medium / Large / GPU** 预设（内存、CPU、GPU），也可以完全自定义。**磁盘是弹性的** —— 存储随数据增长，没有固定上限。
 - **按案例共享容器** —— 多个会话可以 `docker exec` 进同一个容器；结束某个会话绝不会影响其他会话所在的容器。
 - **默认加固** —— 非 root、`--cap-drop ALL`、`no-new-privileges`、PID/内存上限，绝不使用 `--privileged` 或 docker socket；**密封（sealed）** 配置（不注入主机凭据、关闭网络）只需一个开关。
-- **无感认证、凭据隔离** —— 主机上的 Claude / Codex / Gemini / OpenCode 登录在容器内开箱即用：凭据在启动时以只读种子方式复制注入，onboarding/信任提示已预先答复，不会弹出登录向导。容器保留自己的副本，绝不回写主机的凭据存储；跨边界共享的只有对话转录，导出文件也绝不包含机密。
+- **无感认证、凭据隔离** —— 主机上的 Claude / Codex / Antigravity / Gemini / OpenCode / Pi / Grok / OMP 登录在容器内开箱即用：凭据在启动时以只读种子方式复制注入，onboarding/信任提示已预先答复，不会弹出登录向导。容器保留自己的副本，绝不回写主机的凭据存储；跨边界共享的只有对话转录，导出文件也绝不包含机密。
+- **挂到你已经在跑的容器上** —— 在 Docker 面板勾选 **Attach to an existing container**，就能把 case 链接到一个现成容器，而不是新建一个。Codeman 只 `exec` 进去，绝不启动、停止、重启或删除它；一个被接管的容器可以在不同目录下支撑多个 case，**复制一个已有 case** 会用同一容器上的兄弟 case 预填表单。多用户模式下仅管理员可用，因为容器的挂载属于启动它的人。
 - **迁移到另一台机器** —— 把容器的完整环境（工具链 + 工作区）导出为可移植的 `.tar.gz`，在另一台机器上导入到新案例即可继续。
 - **持久耐用** —— Codeman 重启后重连会回到同一个存活的智能体；容器停止/重启后则从绑定挂载的转录恢复对话。
 
@@ -433,6 +492,7 @@ PTY 输出 → 16ms 服务端批处理 → DEC 2026 包裹 → SSE → 客户端
 - **发现与附着**：列出主机上已在运行的 `codeman-*` 会话（由那台机器自己的 Codeman 或其他操作者启动）并附着其一。非你所有的已附着会话在关闭标签时**只分离，绝不杀掉**。
 - **共享会话**：多个客户端可以以不同窗口尺寸同时附着同一个远程会话而互不挤压；发现列表会显示带客户端计数的「shared」徽标。
 - **注入安全**：所有 ssh 命令行都经由单一的 shell 转义构建器生成，主机/路径/身份文件字段均有模式校验。
+- **文件也行**：远程 case 里的预览、下载和文本读取走同一条 ssh 连接（一次 `realpath` + `stat` 探测，然后流式 `cat`，支持 `Range` 拖动进度），所以点一个路径打开的就是智能体所在那台机器上的文件。什么都不会复制到 Codeman 主机；编辑和 Office 预览会明确返回 400，而不是一个误导性的 404。
 
 在 **New Case → Remote** 中配置（主机、用户、身份文件、可选跳板机）。完整设计：[`docs/remote-sessions.md`](docs/remote-sessions.md)。
 
@@ -486,7 +546,7 @@ codeman users list
 systemctl --user enable codeman-tunnel
 loginctl enable-linger $USER
 
-# 或通过 Codeman Web UI：Settings → Tunnel → 切换为开
+# 或通过 Codeman Web UI：App Settings → System → Remote access → Cloudflare Tunnel
 ```
 
 </details>
@@ -588,7 +648,7 @@ Codeman 默认用 `--dangerously-skip-permissions` 启动会话，因此 Web UI
 - **默认仅环回** —— 绑定 `127.0.0.1`，仅可从本机访问，因此「无密码」默认配置开箱即安全。在未设置 `CODEMAN_PASSWORD` 的情况下绑定非环回主机会*启动但打印一条醒目警告*，并给出三个具体修复方案（设置密码、环回 + 一个带认证的隧道，或用 `--allow-unauthenticated-network` 显式确认）
 - **可选认证，真实会话** —— 通过 `CODEMAN_USERNAME`（默认 `admin`）/ `CODEMAN_PASSWORD` 的 HTTP Basic 认证。成功后签发一个不透明的 256 位 `codeman_session` cookie（`randomBytes(32)`）—— 服务端校验，而非客户端签名，因此无法离线伪造（24h TTL、自动延长、设备上下文审计日志）
 - **按 IP 速率限制** —— 失败 10 次 → `429` 并带 `Retry-After`（15 分钟衰减）。即便攻击者在同一 IP 上猛攻，有效 cookie 或正确密码也能*立即*恢复 —— 这很重要，因为所有隧道流量共享同一个环回 IP。二维码认证有自己独立的限制器
-- **可配置的权限模式**：`--dangerously-skip-permissions` 只是默认值。**App Settings → Claude CLI → Startup Mode** 可以把新会话切换为 Anthropic 的分类器护栏 `auto` 模式（低打扰，需要 Claude Code 2.1.207+）、`normal` 提示模式，或一份显式的允许工具列表。多用户模式下，未获授权的用户会被强制为 `auto`，shell 会话与跳过权限需要按用户显式授权
+- **可配置的权限模式**：`--dangerously-skip-permissions` 只是默认值。**App Settings → Agents & CLIs → Claude → Startup Mode** 可以把新会话切换为 Anthropic 的分类器护栏 `auto` 模式（低打扰，需要 Claude Code 2.1.207+）、`normal` 提示模式，或一份显式的允许工具列表。多用户模式下，未获授权的用户会被强制为 `auto`，shell 会话与跳过权限需要按用户显式授权
 
 ### 始终开启的浏览器加固（v0.9.5）
 
@@ -602,8 +662,8 @@ Codeman 默认用 `--dangerously-skip-permissions` 启动会话，因此 Web UI
 
 ### 输入、文件与响应头
 
-- **模式校验的输入** —— 每个 API 请求体都用 Zod v4 模式检查；一个 `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `GEMINI_*` / `GOOGLE_*` 环境变量前缀允许列表把控每个 CLI 能接收哪些设置
-- **路径限定** —— 文件路由在边界检查前先 `realpath`（无 TOCTOU）；`..`、绝对路径、以及解析到工作目录之外的符号链接都会被拒绝。上限：10 MB 文本预览 / 50 MB 原始与下载；`/api/download` 对敏感路径（`.env`、`*credentials*`、`~/.ssh/`、`.aws/credentials`）做黑名单。SVG/HTML 以 `octet-stream` + `nosniff` + attachment 提供，因此会被下载而非执行
+- **模式校验的输入** —— 每个 API 请求体都用 Zod v4 模式检查；一个 `CLAUDE_CODE_*` / `OPENCODE_*` / `CODEX_*` / `ANTIGRAVITY_*` / `GEMINI_*` / `GOOGLE_*` / `PI_*` / `GROK_*` / `XAI_*` / `DSH_*` / `DEEPSEEK_*` / `OMP_*` 环境变量前缀允许列表把控每个 CLI 能接收哪些设置，而那些能把 CLI 流量改道的键（base URL、配置目录）对非管理员用户会被钳制
+- **路径限定** —— 文件路由在边界检查前先 `realpath`（无 TOCTOU）；`..`、绝对路径、以及解析到工作目录之外的符号链接都会被拒绝。上限：10 MB 文本预览 / 2 GB 原始与下载（`CODEMAN_MAX_DOWNLOAD_BYTES`；响应体是流式的并支持 `Range` 请求，所以这个上限只是合理性边界，不是内存保护）；`/api/download` 对敏感路径（`.env`、`*credentials*`、`~/.ssh/`、`.aws/credentials`）做黑名单。SVG/HTML 以 `octet-stream` + `nosniff` + attachment 提供，因此会被下载而非执行
 - **安全响应头** —— `Content-Security-Policy`（`default-src 'self'`，每个例外都逐条列举）、`X-Content-Type-Options: nosniff`、`X-Frame-Options: SAMEORIGIN`、HTTPS 下的 HSTS，以及**仅**对 `localhost` / `127.0.0.1` / `::1` 反射的 CORS
 
 ### 供应链与隔离
@@ -615,17 +675,19 @@ Codeman 默认用 `--dangerously-skip-permissions` 启动会话，因此 Web UI
 
 ---
 
-## SSH 替代方案（`sc`）
+## 终端界面（`codeman tui`）
 
-如果你更喜欢 SSH（Termius、Blink 等），`sc` 命令是一个便于拇指操作的会话选择器：
+一个在终端里运行的全屏会话仪表盘。状态与 Web UI 完全一致，因为它就是同一个服务器的客户端：
 
 ```bash
-sc              # 交互式选择器
-sc 2            # 快速附着到会话 2
-sc -l           # 列出会话
+codeman tui              # 仪表盘
+codeman tui --list       # 带编号的会话列表，随即退出（可用于脚本）
+codeman tui 2            # 直接附着到列表里的第 2 个会话
 ```
 
-单数字选择（1–9）、颜色编码的状态、token 计数、自动刷新。用 `Ctrl+A D` 分离。
+会话按 **NEEDS YOU → WORKING → IDLE → RECENT** 分组，等得最久的排最前。`↑↓`/`j`/`k` 选择，`1`-`9` 与 `[`/`]` 切换会话，`Enter` 附着进 tmux 面板（按 **`F1`** 回来）。在面板里，顶部的横条会一直显示会话条，`Alt+1`-`Alt+9` 不用离开就能切换。`y`/`n`/数字可以直接在列表里回答待处理的权限对话框，`p` 发送一行提示，`n` 新建会话并直接进入，`x` 杀掉一个（`y` 确认），`/` 搜索，`g` 显示离开摘要，`?` 是帮助，`q` 退出。窄于 72 列时它会去掉预览面板、变成单列列表，所以在手机上的 Termius 里依然好用。没有服务器在跑时，它仍会以仅附着的降级模式启动。
+
+Web UI 仍是主要界面；完整指南见 **[docs/tui.md](docs/tui.md)**（英文）。
 
 ---
 
@@ -640,13 +702,21 @@ sc -l           # 列出会话
 | `Ctrl/Cmd+Tab`                  | 下一个会话                                               |
 | `Alt/Option+[` / `Alt/Option+]` | 上一个 / 下一个会话                                      |
 | `Alt/Option+1`–`Alt/Option+9`   | 切换到第 N 个标签（按物理键位，macOS Option 布局也适用） |
+| `Alt/Option+B`                  | 折叠 / 展开会话侧边栏（仅侧边栏布局）                     |
 | `Ctrl+Shift+{` / `Ctrl+Shift+}` | 将当前标签左移 / 右移                                    |
+| `Ctrl/Cmd+C`                    | 复制选中内容；未选中时中断代理                           |
+| `Ctrl+Shift+C`                  | 复制选中内容（永不中断）                                 |
+| `Ctrl/Cmd+V`                    | 粘贴，或上传剪贴板里的图片并粘贴其路径                   |
 | `Ctrl/Cmd+L`                    | 清屏                                                     |
 | `Ctrl+Shift+R`                  | 恢复终端尺寸                                             |
 | `Ctrl+Shift+V`                  | 切换语音输入                                             |
 | `Ctrl/Cmd +` / `-`              | 字体大小                                                 |
 | `Ctrl/Cmd+?`                    | 键盘帮助                                                 |
 | `Shift+Enter`                   | 插入换行（发送到终端）                                   |
+| `Shift+拖动`                    | 在鼠标事件交给 CLI 的面板里选中文本                      |
+| 右键                            | 复制选中内容（没有选中时保留原生菜单）                   |
+| `Shift+滚轮`                    | 滚轮被转发给 CLI 时，滚动本地回滚缓冲区                  |
+| `Ctrl+Z`                        | 在智能体会话里被吞掉，运行中的 CLI 不会被挂起；shell 里照常是作业控制 |
 | `Escape`                        | 关闭面板与模态框                                         |
 
 ---
@@ -655,6 +725,79 @@ sc -l           # 列出会话
 
 面向不经浏览器控制 Codeman 的 AI 智能体与自动化：一个拉起工作会话的智能体、一个 CI 机器人，或是**运行在 Codeman 会话*内部*、编排其他会话的 Claude Code**。UI 能做的一切都是 HTTP + CLI，因此智能体也能做。
 
+### 智能体技能（从这里开始）
+
+这一节的所有内容也打包成了一个 **Claude Code 技能**，位于 [`skills/codeman`](skills/codeman/SKILL.md)。装一次，就再也不用把 API 文档粘进提示词。你用大白话说想要什么，已经坐在 Codeman 会话里的智能体会自己加载配方并驱动 API。
+
+#### 第 1 步：安装
+
+| 方式             | 命令                                                       | 范围                                                                                       |
+| ---------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Skills CLI       | `npx skills add Ark0N/Codeman --skill codeman -g`          | 全局，任何支持技能的智能体都能用                                                           |
+| Claude Code 插件 | `/plugin marketplace add Ark0N/Codeman`，然后 `/plugin install codeman@codeman` | 全局，通过 Claude Code 自带的插件管理器；`/plugin update codeman` 跟随新版本。与 `codeman skill install` 二选一：两者都装会让技能出现两次（`codeman` 和 `codeman:codeman`） |
+| 内置 CLI         | `codeman skill install`                                    | 全局（`~/.claude/skills/codeman`），给那些从 npm 安装、从未克隆过仓库的用户                |
+| 内置 CLI         | `codeman skill install --case <name>`                      | 仅一个 case                                                                                |
+| Web UI           | App Settings → Agents & CLIs → Claude → **Agent Skill**    | 每次在某个 case 创建 Claude 会话时自动注入（`agentSkillEnabled`，跨设备同步，默认关闭）    |
+
+`codeman skill uninstall [--case <name>]` 可以撤销 CLI 安装，并且绝不会碰你自己写的 `skills/codeman`。
+
+#### 第 2 步：开口要
+
+整个界面就这么多。不用 curl，不用端点名，不用会话 id。下面这些提示照原样就能用：
+
+| 你说                                                                                  | 技能做的事                                                                                     |
+| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| _「现在有哪些会话在跑？」_                                                             | 列出它们的名字、模式和状态。只读，随时可以问。                                                 |
+| _「在 `myapp` case 上起一个 shell 工作会话，跑测试套件，告诉我过没过。」_              | 拉起、等待一个拆开的完成标记、读回退出码、清理。                                               |
+| _「起 3 个工作会话分别跑 lint、typecheck 和测试。并行跑，报告失败的。」_               | 扇出流程：每个任务一个会话，先全部启动，再逐个收集完成的。                                     |
+| _「让一个 claude 工作会话在 `refactor-auth` 上总结 `src/session.ts`，然后关掉它。」_  | 拉起、走完就绪阶梯（包括首次运行的信任对话框）、发送并等待、读取干净的 transcript 答案、删除。 |
+| _「盯着会话 w4，如果它卡在权限提示上就告诉我。」_                                      | 阻塞在 `blocked` 信号上，并把问题交给**你**。它绝不会替另一个会话回答提示。                    |
+
+#### 第 3 步：没有了
+
+智能体会删掉它启动的每一个会话。你可以在仪表盘里看着标签出现又消失。
+
+#### 一次真实的运行，从头到尾
+
+> **你：** 起 3 个 shell 工作会话，并行跑 lint / typecheck / 前端语法检查，告诉我哪个失败了。
+
+```text
+lint       -> 9f2d8e5f   dispatched
+typecheck  -> aff9c691   dispatched     仪表盘里出现 3 个标签
+syntax     -> be9f1f15   dispatched
+
+lint         DONE_lint_17909      rc=0
+typecheck    DONE_typecheck_3409  rc=0   每完成一个就收集一个
+syntax       DONE_syntax_18501    rc=0
+
+deleted 9f2d8e5f, aff9c691, be9f1f15    标签消失
+```
+
+那些 `DONE_<task>_<random>` 字符串就是技能的**拆分标记**技巧，也是扇出在没有 hook 的 `shell` 会话上依然可靠的原因：敲进去的那一行只含 `${M}_17909`，因此只有命令真正的*输出*里才会出现 `DONE_17909`。不拆开的标记会在命令还没跑之前就匹配到你自己按键的回显。
+
+#### 盒子里有什么
+
+| 文件                                                                | 内容                                                                                        |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| [`SKILL.md`](skills/codeman/SKILL.md)                               | 安全规则、现成的快速路径（起 N 个工作会话、派任务、收集）和动词索引。始终加载。              |
+| [`reference/verbs.md`](skills/codeman/reference/verbs.md)           | 14 个动词的详细说明：就绪、发送并等待、标记、中断、清理。按需加载。                          |
+| [`reference/recipes.md`](skills/codeman/reference/recipes.md)       | 8 个完整流程：claude、DeepSeek Harness 与 shell 工作会话、扇出、盯住被卡住的工作会话、消息扇出。按需加载。 |
+| [`reference/endpoints.md`](skills/codeman/reference/endpoints.md)   | 完整端点表、错误码、各模式的信号表、容量限制。按需加载。                                     |
+| [`reference/messaging.md`](skills/codeman/reference/messaging.md)   | 通过 Claude Code 跨会话消息直接和 claude 工作会话对话。按需加载。                            |
+
+里面的每一个配方都在真实服务器上验证过，注释记录的是实测出来而不是猜出来的失败模式。
+
+#### 两件值得知道的事
+
+- **它会自我门禁。** 不在 Codeman 会话里（`CODEMAN_MUX` 未设置）时，技能拒绝动作，也不去猜 API 地址，所以全局安装对无关的 Claude Code 会话没有任何代价。
+- **它刻意保守。** 未经提示，它只会拉起会话、给它们发提示，并删除**它在同一段对话里自己创建的**会话（按精确 id，经由一个拒绝删除智能体自身会话的失败即关闭守卫）。删除 case（会抹掉一个真实的代码目录）、批量杀会话、改动 respawn/ralph/cron/orchestrator 以及写设置，都需要你开口并指名目标。
+
+⚠️ 把 `agentSkillEnabled` 关回去**不会删掉已经注入的副本**（在创建时做清扫，会把技能从共用同一个 `.claude/` 目录的其他活动会话脚下抽走）。要删就按 case 删：`codeman skill uninstall --case <name>`。
+
+---
+
+**这一节余下的部分是手动路径**：同样的操作用裸 HTTP 来做，适合 CI 机器人、shell 脚本，或任何不支持技能的智能体。
+
 ### 检测自己身处 Codeman 内部
 
 当 CLI 运行在 Codeman 受管会话中时，以下环境变量会被设置 —— 读取它们，别硬编码任何东西：
@@ -668,15 +811,21 @@ sc -l           # 列出会话
 
 ### 行路规则（POST 之前先读）
 
-1. **只发单行输入。** 编程输入会作为字面文本 **+ Enter** 一次性发送。多行字符串会破坏智能体 TUI（Ink）—— 发送一行，或拆成多次调用。
+1. **只发单行输入，而且必须以 `\r` 结尾。** 编程输入按字面文本发送，**只有当输入里含回车符时才会触发 Enter**：`{"input":"run tests\r"}`。少了 `\r`，文本就停在会话的输入框里不被提交（同一次调用里的 `wait` 还会在一个压根没开始的回合上耗满整个超时）。内嵌的换行会被剥掉而不是报错，因此 `"echo A\necho B\r"` 执行的是拼起来的 `echo Aecho B`：一次调用只发一行。
 2. **让输入幂等。** 在 `POST …/input` 上带上稳定的 `clientId` 和按会话单调递增的 `seq`。服务端会去重，因此连接中断后的重试不会重复投递提示。
-3. **认证。** 若设置了 `CODEMAN_PASSWORD`，发送 HTTP Basic 认证（用户 `admin` 或 `CODEMAN_USERNAME`）或 `codeman_session` cookie。默认的环回安装无密码。缺失的 `Origin` 头被允许，因此普通 `curl` 可用；跨站的浏览器 origin 会被拒绝（CSRF 防护）。
+3. **认证。** 若设置了 `CODEMAN_PASSWORD`，发送 HTTP Basic 认证（用户 `admin` 或 `CODEMAN_USERNAME`）或 `codeman_session` cookie。默认的环回安装无密码。缺失的 `Origin` 头被允许，因此普通 `curl` 可用；跨站的浏览器 origin 会被拒绝（CSRF 防护）。⚠️ `401` 回的是裸字符串 `Unauthorized`，**不是** JSON 信封，直接喂给 `jq` 只会抛解析错误而看不到真正的失败原因：先看状态码，再解析。
 4. **响应信封。** 多数端点返回 `{ "success": true, "data": … }`（错误：`{ "success": false, "error", "errorCode" }`）。少数遗留 GET 返回裸响应体 —— **两种都要处理**（`body.data ?? body`）。
 5. **`/api/v1/*`** 是 `/api/*` 的稳定别名。
+6. **用等待代替轮询，别把超时当成错误。** 等待类端点在没等到事情发生时也以 HTTP `200` 加 `wait.timedOut: true` 应答，所以要循环调用短等待（默认 60 秒），而不是发一个超长的调用：隧道会掐断空闲连接。`wait.timeoutMs` 告诉你服务端钳制之后真正采用的超时（上限 600 秒）。
+7. **只有 `claude` 与 `deepseek` 会话会发出 `stop` 与 `blocked`。** 这两个来自 hook（Claude Code 自己的，以及 DeepSeek Harness 的状态桥接）；`shell` 与其他外部 CLI（opencode/codex/gemini/antigravity/pi/grok/omp）只接受 `idle`、`working` 与 `exit`。在这些模式上显式索要 `stop` 会得到 `400`；不传 `until` 则永远安全。⚠️ `shell` 会话的 `idle` 只在启动时触发**一次**，此后再也不会，所以在那里用「发送并等待」只能等到超时：没有 hook 的会话请用 `wait-output` 标记来同步。
+8. **没有任何东西会报告「就绪」，得自己显式等。** 新会话在 PID 出现之前一律回答 `{"signal":"exit","immediate":true}`（意思是*还没启动*，不是*崩了*），而全新 case 里的 `claude` 工作会话接着会停在 CLI 的信任对话框上。此时给它发提示，等待会在约 2 秒后因 `idle` 解除，看上去和一个跑完的回合一模一样，而文本其实卡在对话框里。下面的配方 2b 就是避开它的顺序。
 
 ### 常用配方
 
 ```bash
+# 每个 Codeman 会话里都自动设好了 CODEMAN_API_URL，协议也是对的。
+# 下面的兜底值适用于标准安装；在 --https 安装上请自己写 https:// 的地址，
+# 并给每个 curl 加上 -k（自签名证书）。
 API="${CODEMAN_API_URL:-http://127.0.0.1:3000}"
 # （若设置了密码，给每个调用加上  -u admin:"$CODEMAN_PASSWORD"）
 
@@ -688,18 +837,69 @@ curl -s -X POST "$API/api/quick-start" \
   -H 'Content-Type: application/json' \
   -d '{"caseName":"refactor-auth","mode":"claude","effort":"high"}' | jq
 
+# 2b. 等这个工作会话真正就绪（见规则 8）：先探输入框的标记，信任对话框只作兜底。
+#     （反过来先探信任对话框、再盲发一个 Enter，在重复运行时会误伤：对话框的文字
+#     会一直留在缓冲区里，探测因此匹配到旧文本，而那个 Enter 落进了已经就绪的输入框。）
+#     匹配单个词：TUI 的文字到达匹配器时可能已经丢掉了词间空格。
+until [ "$(curl -s "$API/api/sessions/$SID" | jq '.data.pid')" != null ]; do sleep 1; done
+R=$(curl -sG "$API/api/sessions/$SID/wait-output" --data-urlencode 'match=bypass' \
+      --data-urlencode 'from=buffer' --data-urlencode 'timeout=5000')
+if ! jq -e '.data.wait.matched' <<<"$R" >/dev/null; then
+  T=$(curl -sG "$API/api/sessions/$SID/wait-output" --data-urlencode 'match=trust' \
+        --data-urlencode 'from=buffer' --data-urlencode 'timeout=2000')
+  jq -e '.data.wait.matched' <<<"$T" >/dev/null && \
+    curl -s -X POST "$API/api/sessions/$SID/input" -H 'Content-Type: application/json' \
+      -d '{"input":"\r","useMux":true}'        # 接受首次运行的信任对话框
+  curl -sG "$API/api/sessions/$SID/wait-output" --data-urlencode 'match=bypass' \
+    --data-urlencode 'from=buffer' --data-urlencode 'timeout=45000' >/dev/null
+fi
+
 # 3. 向会话发送提示（精确一次：clientId + seq）
 curl -s -X POST "$API/api/sessions/$SID/input" \
   -H 'Content-Type: application/json' \
-  -d '{"input":"Run the test suite and summarize failures","useMux":true,"clientId":"agent-1","seq":1}'
+  -d '{"input":"Run the test suite and summarize failures\r","useMux":true,"clientId":"agent-1","seq":1}'
 
-# 4. 读回终端内容
-curl -s "$API/api/sessions/$SID/output" | jq -r '.data // .'
+# 4. 发送提示并阻塞到这一回合结束（先注册等待再写入，因此不会拿上一回合的状态来应答）
+curl -s -X POST "$API/api/sessions/$SID/input" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"Run the test suite and summarize failures\r","useMux":true,
+       "clientId":"agent-1","seq":2,"wait":"stop,exit","waitTimeout":60000}' \
+  | jq '.data.wait'      # -> {"signal":"stop","timedOut":false,"waitedMs":41230,...}
+#    （`stop` 是回合结束的权威 hook。加上 `idle` 会让它在转圈停顿时也解除，
+#      任何重画出 ❯ 提示符的东西同理，比如一个对话框。）
 
-# 5. 流式接收实时事件（会话输出、智能体活动、状态）
+# 4b. 超时了？那是 200，不是失败。循环调用短等待即可。
+curl -s "$API/api/sessions/$SID/wait?until=stop,exit&timeout=60000" | jq '.data.wait'
+
+# 4c. 或者等输出里出现某个标记（shell 会话也适用）。
+#     ⚠️ 每次调用都要用不同的标记（tmux 重画会重放旧屏幕文字），并且把标记拆开写，
+#     让敲进去的那一行本身不包含它：你自己的按键会回显进输出流，不拆开的标记会在
+#     命令还没跑之前就匹配上。from=buffer 用来接住在等待落地之前就已打印的标记。
+N=$RANDOM
+curl -s -X POST "$API/api/sessions/$SID/input" -H 'Content-Type: application/json' \
+  -d "{\"input\":\"M=DONE; npm test; echo \${M}_$N rc=\$?\r\",\"useMux\":true}"
+curl -sG "$API/api/sessions/$SID/wait-output" \
+  --data-urlencode "match=DONE_$N" --data-urlencode 'from=buffer' \
+  --data-urlencode 'timeout=60000' | jq '.data.wait'
+
+# 5. 读回答案。claude / codex / deepseek 会话用 last-response：它取自 transcript 而不是屏幕，
+#    因此不带 TUI 的画框与重画噪声。⚠️ 要轮询，别只读一次：transcript 落盘比 stop
+#    信号稍晚，紧跟着「发送并等待」返回后立刻读，常常拿到空串。
+for _ in $(seq 1 10); do
+  TXT=$(curl -s "$API/api/sessions/$SID/last-response" | jq -r '.data.text')
+  [ -n "$TXT" ] && break; sleep 1
+done
+printf '%s\n' "$TXT"
+
+# 5b. 其他模式（shell/opencode/gemini/antigravity/pi/grok/omp）没有 transcript，读终端。
+#     ⚠️ 用 terminal?tail=，不要用 /output：后者的 textOutput 对每个由 tmux 承载的
+#     （也就是每个交互式）会话都是空的。tail 按字节计，返回的是含 ANSI 的终端数据。
+curl -s "$API/api/sessions/$SID/terminal?tail=8000" | jq -r '.data.terminalBuffer'
+
+# 6. 流式接收实时事件（会话输出、智能体活动、状态）
 curl -sN "$API/api/events"          # Server-Sent Events
 
-# 6. 调度周期性工作（cron 风格任务）
+# 7. 调度周期性工作（cron 风格任务）
 curl -s -X POST "$API/api/cron/jobs" \
   -H 'Content-Type: application/json' \
   -d '{"name":"nightly-deps","agentType":"claude","workingDir":"/home/me/proj",
@@ -707,11 +907,11 @@ curl -s -X POST "$API/api/cron/jobs" \
        "inputMode":"typed","scheduleType":"daily","dailyTime":"03:00",
        "enabled":true,"concurrencyPolicy":"warn_only"}' | jq
 
-# 7. 查看后台子智能体及其活动记录
+# 8. 查看后台子智能体及其活动记录
 curl -s "$API/api/subagents" | jq '.data // .'
 curl -s "$API/api/subagents/$AID/transcript" | jq -r '.data // .'
 
-# 8. 全系统快照（会话、设置、重生、统计）
+# 9. 全系统快照（会话、设置、重生、统计）
 curl -s "$API/api/status" | jq
 ```
 
@@ -724,7 +924,9 @@ codeman session start -d /path/to/repo   # (s)  启动会话
 codeman session list                     #      列出会话
 codeman session logs <id>                #      查看输出
 codeman task add "fix the failing test"  # (t)  排入任务
-codeman attach <path>                    #      附着 Claude hook 上下文
+codeman attach <path>                    #      为本地文件显示一张附件卡片
+codeman tui --list                       #      带编号的会话列表（管道输出时为纯文本）
+codeman tui 3                            #      附着到该列表里的第 3 个会话
 ```
 
 ### Hook（事件*回流*到 Codeman）
@@ -737,20 +939,25 @@ Codeman 会注册 Claude Code hook，它们 `POST /api/hook-event`（`permission
 
 ## API
 
-基于 Fastify 的 REST —— **20 个路由模块中约 190 个处理器**，外加一条 SSE 流和一条 WebSocket 终端通道。所有响应都使用 `ApiResponse<T>` 信封（`{success, data}` / `{success, error, errorCode}`）；`/api/v1/*` 是稳定别名。以下是一个有代表性的子集：
+基于 Fastify 的 REST —— **25 个路由模块中约 230 个处理器**，外加一条 SSE 流和一条 WebSocket 终端通道。所有响应都使用 `ApiResponse<T>` 信封（`{success, data}` / `{success, error, errorCode}`）；`/api/v1/*` 是稳定别名。以下是一个有代表性的子集：
 
 ### 会话（Sessions）
 
-| 方法     | 端点                       | 说明                                                                           |
-| -------- | -------------------------- | ------------------------------------------------------------------------------ |
-| `GET`    | `/api/sessions`            | 列出全部                                                                       |
-| `POST`   | `/api/quick-start`         | 创建 case + 启动会话（`{caseName?, mode?, effort?, envOverrides?}`）           |
-| `POST`   | `/api/sessions/:id/input`  | 发送输入（`{input, useMux?, clientId?, seq?}` —— `clientId`+`seq` = 精确一次） |
-| `GET`    | `/api/sessions/:id/output` | 读取终端输出                                                                   |
-| `GET`    | `/api/sessions/unified`    | 统一的活动 + 历史清单（会话管理器）：`?q=&limit=`                              |
-| `POST`   | `/api/sessions/:id/pin`    | 在会话管理器中置顶 / 取消置顶（`{pinned}`）                                    |
-| `PUT`    | `/api/session-order`       | 跨设备同步标签顺序（`{order: [ids]}`）                                         |
-| `DELETE` | `/api/sessions/:id`        | 删除会话                                                                       |
+| 方法     | 端点                            | 说明                                                                                                                         |
+| -------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `GET`    | `/api/sessions`                 | 列出全部                                                                                                                     |
+| `POST`   | `/api/quick-start`              | 创建 case + 启动会话（`{caseName?, mode?, effort?, envOverrides?}`）                                                         |
+| `POST`   | `/api/sessions/:id/input`       | 发送输入（`{input, useMux?, clientId?, seq?, wait?, waitTimeout?}`：`clientId`+`seq` = 精确一次；`wait` 阻塞到这一回合结束） |
+| `GET`    | `/api/sessions/:id/terminal`    | 读取终端输出（`?tail=<bytes>`、`?full=1`）：交互式会话的读取路径                                                             |
+| `GET`    | `/api/sessions/:id/output`      | 一次性的解析输出（tmux 承载的会话里 `textOutput` 为空）                                                                      |
+| `GET`    | `/api/sessions/:id/last-response` | 从 transcript 读出的最后一条回答，纯文本（claude、codex、deepseek）                                                        |
+| `GET`    | `/api/sessions/:id/wait`        | 阻塞到某个信号触发（`?until=stop,idle,exit&timeout=&fresh=`）；超时是 `200`                                                  |
+| `GET`    | `/api/sessions/:id/wait-output` | 阻塞到某个字面串出现（`?match=&nocase=&from=now\|buffer&timeout=`）                                                          |
+| `GET`    | `/api/sessions/unified`         | 统一的活动 + 历史清单（会话管理器）：`?q=&limit=`                                                                            |
+| `POST`   | `/api/sessions/:id/pin`         | 在会话管理器中置顶 / 取消置顶（`{pinned}`）                                                                                  |
+| `PUT`    | `/api/session-order`            | 跨设备同步标签顺序（`{order: [ids]}`）                                                                                       |
+| `POST`   | `/api/sessions/:id/custom-model` | 让会话的 CLI 在一个已保存的自定义端点上原地重启（`{endpointId, modelId}`；`{clear: true}` 回到官方后端）                    |
+| `DELETE` | `/api/sessions/:id`             | 删除会话                                                                                                                     |
 
 ### 重生（Respawn）
 
@@ -798,8 +1005,11 @@ Codeman 会注册 Claude Code hook，它们 `POST /api/hook-event`（`permission
 | `GET`  | `/api/system/update/check`      | 检查新发行版                             |
 | `POST` | `/api/system/update`            | 自更新（git-clone 安装）                 |
 | `POST` | `/api/clipboard`                | 把文本推送到所有已连接浏览器（`{text}`） |
+| `GET` / `POST` | `/api/model-endpoints`  | 列出 / 保存自定义的 OpenAI 兼容端点（`PUT` / `DELETE` `/:id`；多用户模式下仅管理员） |
 | `GET`  | `/api/sessions/:id/run-summary` | 时间线 + 统计                            |
 
+> **想在 Codeman 之上做集成？**[`docs/extending-codeman.md`](docs/extending-codeman.md)（英文）是集成指南：把你自己的界面作为标签页嵌入、订阅 SSE 事件流以便在 agent 需要你时做出响应、用脚本驱动 Codeman，以及动手前值得先了解的那些坑。Codeman 刻意不提供插件运行时，所以一个集成就是你自己的进程在讲 HTTP。
+
 ---
 
 ## 架构
@@ -832,7 +1042,7 @@ flowchart TB
         end
 
         subgraph External["外部"]
-            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Gemini</small>"]
+            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Antigravity / Gemini / Pi / Grok / DeepSeek / OMP</small>"]
             BG["后台智能体<br/><small>(Task 工具)</small>"]
         end
     end
@@ -863,13 +1073,19 @@ flowchart TB
 npm install
 npx tsx src/index.ts web    # 开发模式
 npm run build               # 生产构建
-npm run test:ci             # 运行测试（CI 套件；浏览器套件需要额外环境）
+npm test                    # 运行测试（与 CI 相同；浏览器/移动端/性能套件另有独立命令）
 ```
 
 完整文档见 [CLAUDE.md](./CLAUDE.md)。
 
 ---
 
+## 社区
+
+提问、安装求助和想法都在 [GitHub Discussions](https://github.com/Ark0N/Codeman/discussions)：[Q&A 板块](https://github.com/Ark0N/Codeman/discussions/categories/q-a)回答了最常见的那些（手机访问、通宵运行、更新），路线图则在 [Ideas](https://github.com/Ark0N/Codeman/discussions/categories/ideas) 里决定。Bug 请提到 [issues](https://github.com/Ark0N/Codeman/issues)；报告通常一天内会得到回复，每个发行版都会点名感谢报告者和贡献者。想参与贡献？[CONTRIBUTING.md](.github/CONTRIBUTING.md) 是地图：皮肤、翻译和文档都是很好的第一个 PR，更大的特性先从一个 Discussion 开始。如果你对自己的配置很自豪，发到 [Show and tell](https://github.com/Ark0N/Codeman/discussions/300) 来。
+
+---
+
 ## 代码库质量
 
 本代码库经历了一次全面的 7 阶段重构，消除了上帝对象、集中了配置，并建立了模块化架构：
@@ -893,7 +1109,7 @@ npm run test:ci             # 运行测试（CI 套件；浏览器套件需要
 
 [![npm](https://img.shields.io/npm/v/xterm-zerolag-input?style=flat-square&color=22c55e)](https://www.npmjs.com/package/xterm-zerolag-input)
 
-为 xterm.js 提供即时按键反馈的叠加层。通过把输入的字符立即渲染为像素级精准的 DOM 叠加层，消除高 RTT 连接下的感知输入延迟。零依赖、可配置的提示符检测、带 78 个测试的完整状态机。
+为 xterm.js 提供即时按键反馈的叠加层。通过把输入的字符立即渲染为像素级精准的 DOM 叠加层，消除高 RTT 连接下的感知输入延迟。零依赖、gzip 后 6.1 kB、可配置的提示符检测、CJK/emoji 宽字符支持、带 238 个测试的完整状态机。
 
 ```bash
 npm install xterm-zerolag-input
@@ -916,3 +1132,8 @@ MIT —— 见 [LICENSE](LICENSE)
 <p align="center">
   <strong>跟踪会话。可视化智能体。掌控重生。让它在你睡觉时持续运行。</strong>
 </p>
+
+<p align="center">
+  如果 Codeman 帮你省了时间，<a href="https://github.com/Ark0N/Codeman/stargazers">点个 star</a> 能让更多人找到它。<br>
+  欢迎到 <a href="https://github.com/Ark0N/Codeman/issues">Issues</a> 报告 bug 和提出特性想法。
+</p>

config/clis.stock.json

@@ -0,0 +1,281 @@
+[
+  {
+    "id": "claude",
+    "label": "Claude Code",
+    "shortBadge": "CC",
+    "enabled": true,
+    "order": 0,
+    "kind": "agent",
+    "discovery": {
+      "binaries": [
+        "claude"
+      ],
+      "searchDirs": [
+        "~/.local/bin",
+        "~/.claude/local",
+        "/usr/local/bin",
+        "~/.npm-global/bin",
+        "~/bin"
+      ],
+      "install": {
+        "command": {
+          "linux": "curl -fsSL https://claude.ai/install.sh | bash",
+          "darwin": "curl -fsSL https://claude.ai/install.sh | bash",
+          "wsl": "curl -fsSL https://claude.ai/install.sh | bash"
+        },
+        "npmPackage": "@anthropic-ai/claude-code",
+        "docsUrl": "https://docs.claude.com/claude-code"
+      }
+    }
+  },
+  {
+    "id": "shell",
+    "label": "Shell",
+    "shortBadge": "SH",
+    "enabled": true,
+    "order": 1,
+    "kind": "shell",
+    "discovery": {
+      "binaries": [],
+      "searchDirs": [],
+      "install": {
+        "command": {}
+      }
+    }
+  },
+  {
+    "id": "opencode",
+    "label": "OpenCode",
+    "shortBadge": "OC",
+    "enabled": true,
+    "order": 10,
+    "kind": "agent",
+    "discovery": {
+      "binaries": [
+        "opencode"
+      ],
+      "searchDirs": [
+        "~/.opencode/bin",
+        "~/.local/bin",
+        "/usr/local/bin",
+        "~/go/bin",
+        "~/.bun/bin",
+        "~/.npm-global/bin",
+        "~/bin"
+      ],
+      "install": {
+        "command": {
+          "linux": "curl -fsSL https://opencode.ai/install | bash",
+          "darwin": "curl -fsSL https://opencode.ai/install | bash"
+        },
+        "npmPackage": "opencode-ai",
+        "docsUrl": "https://opencode.ai/docs"
+      }
+    }
+  },
+  {
+    "id": "codex",
+    "label": "Codex",
+    "shortBadge": "CX",
+    "enabled": true,
+    "order": 20,
+    "kind": "agent",
+    "discovery": {
+      "binaries": [
+        "codex"
+      ],
+      "searchDirs": [
+        "~/.codex/bin",
+        "~/.local/bin",
+        "/usr/local/bin",
+        "~/.bun/bin",
+        "~/.npm-global/bin",
+        "~/bin"
+      ],
+      "install": {
+        "command": {
+          "linux": "npm install -g @openai/codex",
+          "darwin": "npm install -g @openai/codex"
+        },
+        "npmPackage": "@openai/codex",
+        "docsUrl": "https://developers.openai.com/codex/cli"
+      }
+    }
+  },
+  {
+    "id": "gemini",
+    "label": "Gemini",
+    "shortBadge": "GM",
+    "enabled": true,
+    "order": 30,
+    "kind": "agent",
+    "discovery": {
+      "binaries": [
+        "gemini"
+      ],
+      "searchDirs": [
+        "~/.gemini/bin",
+        "~/.local/bin",
+        "/usr/local/bin",
+        "~/.bun/bin",
+        "~/.npm-global/bin",
+        "~/bin"
+      ],
+      "install": {
+        "command": {
+          "linux": "npm install -g @google/gemini-cli",
+          "darwin": "npm install -g @google/gemini-cli"
+        },
+        "npmPackage": "@google/gemini-cli",
+        "docsUrl": "https://github.com/google-gemini/gemini-cli"
+      }
+    }
+  },
+  {
+    "id": "antigravity",
+    "label": "Antigravity",
+    "shortBadge": "AG",
+    "enabled": true,
+    "order": 40,
+    "kind": "agent",
+    "discovery": {
+      "binaries": [
+        "agy"
+      ],
+      "searchDirs": [
+        "~/.local/bin",
+        "~/.antigravity/bin",
+        "/usr/local/bin",
+        "~/bin"
+      ],
+      "install": {
+        "command": {
+          "linux": "curl -fsSL https://antigravity.google/cli/install.sh | bash",
+          "darwin": "curl -fsSL https://antigravity.google/cli/install.sh | bash"
+        },
+        "docsUrl": "https://antigravity.google/cli"
+      }
+    }
+  },
+  {
+    "id": "pi",
+    "label": "Pi",
+    "shortBadge": "PI",
+    "enabled": true,
+    "order": 50,
+    "kind": "agent",
+    "discovery": {
+      "binaries": [
+        "pi"
+      ],
+      "searchDirs": [
+        "~/.local/bin",
+        "/usr/local/bin",
+        "~/.bun/bin",
+        "~/.npm-global/bin",
+        "~/bin"
+      ],
+      "install": {
+        "command": {
+          "linux": "npm install -g --ignore-scripts @earendil-works/pi-coding-agent",
+          "darwin": "npm install -g --ignore-scripts @earendil-works/pi-coding-agent"
+        },
+        "npmPackage": "@earendil-works/pi-coding-agent",
+        "docsUrl": "https://pi.dev",
+        "agentImageLayer": {
+          "kind": "dedicated",
+          "reason": "installed with --ignore-scripts in its own layer, so the flag cannot leak to the shared block"
+        }
+      }
+    }
+  },
+  {
+    "id": "grok",
+    "label": "Grok",
+    "shortBadge": "GK",
+    "enabled": true,
+    "order": 70,
+    "kind": "agent",
+    "discovery": {
+      "binaries": [
+        "grok"
+      ],
+      "searchDirs": [
+        "~/.grok/bin",
+        "~/.local/bin",
+        "/usr/local/bin",
+        "~/bin"
+      ],
+      "install": {
+        "command": {
+          "linux": "curl -fsSL https://x.ai/cli/install.sh | bash",
+          "darwin": "curl -fsSL https://x.ai/cli/install.sh | bash"
+        },
+        "docsUrl": "https://github.com/xai-org/grok-build"
+      }
+    }
+  },
+  {
+    "id": "deepseek",
+    "label": "DeepSeek",
+    "shortBadge": "DS",
+    "enabled": true,
+    "order": 80,
+    "kind": "agent",
+    "discovery": {
+      "binaries": [
+        "dsh"
+      ],
+      "searchDirs": [
+        "~/.local/bin",
+        "/usr/local/bin",
+        "~/.npm-global/bin",
+        "~/bin"
+      ],
+      "identity": {
+        "arg": "--help",
+        "regex": "DeepSeek\\s+Harness"
+      },
+      "install": {
+        "command": {
+          "linux": "npm install -g @deepseek-ai/dsh",
+          "darwin": "npm install -g @deepseek-ai/dsh"
+        },
+        "npmPackage": "@deepseek-ai/dsh",
+        "docsUrl": "https://github.com/deepseek-ai/deepseek-harness",
+        "agentImageLayer": {
+          "kind": "dedicated",
+          "reason": "needs pnpm alongside it (dsh plugin, issue #352) and a dsh-tui profile install"
+        }
+      }
+    }
+  },
+  {
+    "id": "omp",
+    "label": "OMP",
+    "shortBadge": "OM",
+    "enabled": true,
+    "order": 90,
+    "kind": "agent",
+    "discovery": {
+      "binaries": [
+        "omp"
+      ],
+      "searchDirs": [
+        "~/.local/bin",
+        "~/.omp/bin",
+        "/usr/local/bin",
+        "~/.bun/bin",
+        "~/.npm-global/bin",
+        "~/bin"
+      ],
+      "install": {
+        "command": {
+          "linux": "curl -fsSL https://omp.sh/install | sh",
+          "darwin": "brew install can1357/tap/omp"
+        },
+        "docsUrl": "https://omp.sh"
+      }
+    }
+  }
+]

config/test-suites.ts

@@ -0,0 +1,54 @@
+/**
+ * The test suites that `npm test` deliberately does NOT run, in one place.
+ *
+ * Why this file exists: the exclusion list used to live only in
+ * config/vitest.ci.config.ts, as literals. Anything excluded there was
+ * therefore reachable only by running the everything-config by hand and reading
+ * past its failures — and a newly excluded file was reachable by nothing at
+ * all, silently, because nothing pointed at it. Both configs now derive their
+ * globs from the arrays below, so adding a suite here puts it in exactly one
+ * runner and takes it out of exactly one gate.
+ *
+ * Adding a new test that cannot run in CI: put its glob in the array that
+ * describes WHY it cannot, not in whichever one is shortest.
+ */
+
+/**
+ * Playwright-driven: needs chromium and, in most cases, a live Codeman server
+ * on a real port. Deterministic where the environment provides both, which is
+ * why these are a runnable suite (`npm run test:browser`) rather than skipped.
+ */
+export const BROWSER_TEST_GLOBS = [
+  'test/tab-rail-resize.browser.test.ts',
+  'test/session-sidebar-ux.browser.test.ts',
+  'test/session-options-responsive.browser.test.ts',
+  'test/inline-rename.test.ts',
+  'test/opencode-resize.test.ts',
+  'test/webgl-fallback.test.ts',
+  'test/terminal-copy-shortcut.test.ts',
+  'test/terminal-keycode229-recovery.browser.test.ts',
+  'test/capture-load-window.browser.test.ts',
+  'test/capture-geometry-retry.browser.test.ts',
+  'test/codex-predictive-echo.test.ts', // also needs a real codex binary
+  'test/split-pane-terminal.browser.test.ts',
+  'test/split-pane-orchestration.browser.test.ts',
+  'test/split-pane-auto-collapse.browser.test.ts',
+];
+
+/**
+ * Wall-clock benchmarks. They assert on durations, so a loaded shared runner
+ * fails them for reasons that have nothing to do with the diff under test.
+ */
+export const PERF_TEST_GLOBS = ['test/perf-*.test.ts'];
+
+/**
+ * Browser + visual regression: chromium AND environment-specific PNG baselines
+ * that are generated per machine. Has its own config
+ * (test/mobile/vitest.config.ts) because it needs serial execution, a longer
+ * timeout and the `pretest:mobile` vendor step — run it with
+ * `npm run test:mobile`, not through the configs here.
+ */
+export const MOBILE_TEST_GLOBS = ['test/mobile/**'];
+
+/** Everything `npm test` skips. */
+export const NON_CI_TEST_GLOBS = [...MOBILE_TEST_GLOBS, ...PERF_TEST_GLOBS, ...BROWSER_TEST_GLOBS];

config/tsconfig.scripts.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "noEmit": true,
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": false
+  },
+  "include": ["../scripts/test-local-llm-harnesses.ts"]
+}

config/vitest.browser.config.ts

@@ -0,0 +1,34 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'vitest/config';
+import { BROWSER_TEST_GLOBS } from './test-suites';
+
+const root = resolve(import.meta.dirname, '..');
+
+/**
+ * The Playwright-driven suite `npm test` skips — `npm run test:browser`.
+ *
+ * Needs chromium and, for most of these, a live Codeman server on a real port;
+ * codex-predictive-echo also needs a real codex binary. Expect failures where
+ * the machine cannot provide those, and read them as "not runnable here", not
+ * as a regression.
+ *
+ * The mobile suite is NOT here: it needs per-machine PNG baselines, serial
+ * execution and the `pretest:mobile` vendor step, so it keeps its own config
+ * (test/mobile/vitest.config.ts) behind `npm run test:mobile`.
+ *
+ * fileParallelism stays off for the same reason as every other config in this
+ * directory: these bind real ports and drive real tmux sessions, and two files
+ * doing that at once fail each other rather than the code.
+ */
+export default defineConfig({
+  test: {
+    root,
+    globals: true,
+    environment: 'node',
+    include: BROWSER_TEST_GLOBS,
+    setupFiles: ['./test/setup.ts'],
+    fileParallelism: false,
+    testTimeout: 60000,
+    teardownTimeout: 60000,
+  },
+});

config/vitest.ci.config.ts

@@ -1,13 +1,17 @@
 import { resolve } from 'node:path';
 import { defineConfig, configDefaults } from 'vitest/config';
+import { NON_CI_TEST_GLOBS } from './test-suites';
 
 const root = resolve(import.meta.dirname, '..');
 
 /**
- * CI test config — same as vitest.config.ts but EXCLUDES the browser-driven
- * mobile suite (test/mobile/**). Those are Playwright visual-regression tests
- * that need a live server + chromium + environment-specific PNG baselines, so
- * they are run/maintained separately and are not part of the CI gate.
+ * The default gate — what `npm test` and CI both run.
+ *
+ * Same as vitest.config.ts but EXCLUDES the suites that cannot pass on an
+ * arbitrary machine: browser-driven (Playwright + chromium), visual-regression
+ * (per-machine PNG baselines) and wall-clock perf. Those are not unmaintained;
+ * they have their own runners (`test:browser`, `test:mobile`, `test:perf`).
+ * See config/test-suites.ts for the list and the reason behind each entry.
  *
  * Keep the rest in sync with config/vitest.config.ts.
  */
@@ -17,14 +21,7 @@ export default defineConfig({
     globals: true,
     environment: 'node',
     include: ['test/**/*.test.ts'],
-    exclude: [
-      ...configDefaults.exclude,
-      'test/mobile/**', // browser/visual (Playwright + chromium)
-      'test/perf-*.test.ts', // timing-sensitive perf benchmarks (flaky in CI)
-      'test/inline-rename.test.ts', // browser (Playwright)
-      'test/opencode-resize.test.ts', // browser (Playwright)
-      'test/webgl-fallback.test.ts', // browser (Playwright)
-    ],
+    exclude: [...configDefaults.exclude, ...NON_CI_TEST_GLOBS],
     setupFiles: ['./test/setup.ts'],
     fileParallelism: false,
     testTimeout: 30000,

config/vitest.config.ts

@@ -3,6 +3,17 @@ import { defineConfig } from 'vitest/config';
 
 const root = resolve(import.meta.dirname, '..');
 
+/**
+ * EVERY test in the repo, including the ones that cannot pass on an arbitrary
+ * machine — `npm run test:all`. Reach for it when you want the complete picture
+ * and are prepared to read past environmental failures.
+ *
+ * This is NOT what `npm test` runs. On a machine without chromium, a free port
+ * or per-machine PNG baselines this config fails ~87 tests on a clean master,
+ * which makes it useless as a pass/fail signal: the default gate is
+ * config/vitest.ci.config.ts, and the suites it leaves out each have their own
+ * runner (`test:browser`, `test:perf`, `test:mobile`). See config/test-suites.ts.
+ */
 export default defineConfig({
   test: {
     root,

config/vitest.perf.config.ts

@@ -0,0 +1,25 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'vitest/config';
+import { PERF_TEST_GLOBS } from './test-suites';
+
+const root = resolve(import.meta.dirname, '..');
+
+/**
+ * The wall-clock benchmarks `npm test` skips — `npm run test:perf`.
+ *
+ * These assert on durations, so run them on an otherwise idle machine: a loaded
+ * runner fails them for reasons that have nothing to do with the diff under
+ * test, which is exactly why they are not part of the default gate.
+ */
+export default defineConfig({
+  test: {
+    root,
+    globals: true,
+    environment: 'node',
+    include: PERF_TEST_GLOBS,
+    setupFiles: ['./test/setup.ts'],
+    fileParallelism: false,
+    testTimeout: 60000,
+    teardownTimeout: 60000,
+  },
+});

docker/.env.example

@@ -0,0 +1,96 @@
+# =============================================================================
+# Codeman Docker Compose environment template
+# Copy this file to .env and set the values for the Docker host.
+# =============================================================================
+
+TZ=Australia/Perth
+
+# Optional overrides for direct `docker compose` use. The Bash start script
+# detects these values from CODEMAN_APPDATA_PATH automatically. Compose uses
+# 1000:1000 when the variables are omitted.
+# PUID=1000
+# PGID=1000
+
+# Name of the account that runs Codeman and all local CLI sessions. Changing
+# this value rebuilds the image with a matching account.
+CODEMAN_RUNTIME_USER=codeman
+
+# Optional Git identity for commits made by Codeman and Docker-case agents. These values
+# are written to each image's system Git configuration when it is rebuilt, so
+# deployments can configure a consistent default. Set both values together.
+# GIT_USER_NAME=
+# GIT_USER_EMAIL=
+
+# Required. Persistent Codeman application data, CLI credentials, and session
+# state are stored here on the host and mounted at the runtime account's home
+# directory in the container.
+CODEMAN_APPDATA_PATH=/mnt/user/appdata/codeman
+
+# Optional. Absolute host path of this Codeman checkout, mounted at
+# /opt/codeman so App Settings -> Updates can update Codeman in place. The Bash
+# start script detects it from the compose file's own location, so it only needs
+# setting for direct `docker compose` use or a checkout kept elsewhere. Point it
+# at a directory that is not a git checkout and in-app updates are unavailable.
+# CODEMAN_REPO_PATH=/mnt/user/appdata/codeman/app
+
+# Required for Docker cases. This must be an absolute path on the Docker host.
+# Codeman and each isolated case use this same path, so it cannot be a
+# container-only path such as /home/codeman/codeman-cases.
+CODEMAN_CASES_PATH=/mnt/user/appdata/codeman/codeman-cases
+
+# Required. Network bind address, host port, and local image tag.
+CODEMAN_HOST=0.0.0.0
+CODEMAN_PORT=3000
+CODEMAN_IMAGE=codeman:local
+
+# Required for any network-accessible Codeman instance. Use a unique, strong
+# password. This file is safe to commit; copy it to .env and set the value.
+CODEMAN_PASSWORD=changeme
+
+# Required. Username for Codeman HTTP Basic authentication.
+CODEMAN_USERNAME=admin
+
+# Optional. Extra Host-header allowlist entries for a reverse-proxied domain
+# (comma-separated; a bare `.suffix` matches every subdomain). Without it a
+# proxied request is rejected with `403 Forbidden: host not allowed`. See
+# 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=
+
+# Linux default. On Docker Desktop, use the socket path supported by your
+# Docker installation when it differs from /var/run/docker.sock.
+DOCKER_SOCKET=/var/run/docker.sock
+
+# Optional override for direct `docker compose` use. The Bash start script
+# detects this from DOCKER_SOCKET automatically. The direct Compose default is
+# 999, but the correct value depends on the Docker host.
+# DOCKER_SOCKET_GID=999
+
+# Set to 1 only when Docker-case hook callbacks are required.
+CODEMAN_DOCKER_BRIDGE_HOOKS=0
+
+# Set to 1 when `docker info` reports `SwapLimit=false`. The case memory limit
+# remains active; Codeman omits --memory-swap and filters the daemon's exact
+# unsupported-swap warning while preserving all other Docker create errors.
+CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=0
+
+# Required only when applying the macvlan example in README.md.
+CODEMAN_MACVLAN_NETWORK=br0.11
+CODEMAN_IPV4_ADDRESS=10.10.11.236
+CODEMAN_MAC_ADDRESS=02:10:11:00:00:EC
+
+# Required only when creating a new managed macvlan network, rather than using
+# the external-network macvlan example.
+CODEMAN_MACVLAN_PARENT=br0.11
+CODEMAN_MACVLAN_SUBNET=10.10.11.0/24
+CODEMAN_MACVLAN_GATEWAY=10.10.11.1

docker/README.md

@@ -0,0 +1,257 @@
+# Codeman Docker deployment
+
+This folder contains the Compose configuration, server image Dockerfile, and environment template for a locally built Codeman server.
+
+## Start
+
+From the repository root, create the runtime environment file and set the required values, especially `CODEMAN_PASSWORD`.
+
+```sh
+cp docker/.env.example docker/.env
+bash docker/Start-Codeman.sh
+```
+
+On PowerShell, use the following commands instead. Running Compose from inside `docker/` with no `-f` lets it discover `docker-compose.override.yml` on its own (see [Local customisation](#local-customisation)); naming the file with `-f docker/docker-compose.yaml` from the repository root silently drops the override unless it is named too.
+
+```powershell
+Copy-Item docker/.env.example docker/.env
+Set-Location docker
+docker compose --env-file .env up --build -d
+```
+
+Every required value is defined and explained in `.env.example`. `GEMINI_API_KEY` is intentionally optional and may remain blank.
+
+The container starts as root so `entrypoint.sh` can correct the ownership of a bind source the Docker daemon created (it creates a missing one as `root:root`), then drops to `PUID:PGID` with `setpriv` before the server starts, so Codeman itself never runs privileged. That drop needs `cap_add: [CHOWN, DAC_OVERRIDE, KILL, SETGID, SETUID]` against the file's `cap_drop: ALL`; a compose file written elsewhere (Unraid's Compose Manager, a hand-written unit) must carry the same additions, and the entrypoint names them when they are missing. A directory owned by neither root nor `PUID:PGID` is never re-owned: it is probed for writability as the runtime account and refused with a clear message if that fails. Setting `user:` in Compose skips the whole step.
+
+On Linux, `Start-Codeman.sh` stops with an error when required paths are missing. It creates the application-data directory when safe, detects its numeric owner as `PUID:PGID`, and detects `DOCKER_SOCKET_GID` from the configured Docker socket. It rejects a root-owned application-data directory because Codeman and its local CLI sessions must remain unprivileged.
+
+Codeman, Claude, OpenCode, and other local sessions run as the unprivileged account named by `CODEMAN_RUNTIME_USER`, which defaults to `codeman`. When Compose is run directly, `PUID` and `PGID` default to `1000:1000`; set them in `.env` when the application-data directory has a different owner. The Bash start script determines them automatically instead.
+
+To retain Docker-case support without root when running Compose directly, set `DOCKER_SOCKET_GID` to the numeric group ID of the host socket. On a standard Linux Docker host, obtain it with `stat -c '%g' /var/run/docker.sock`. The Bash start script detects it automatically.
+
+## Updating
+
+Use **App Settings → Updates** in the web UI. The checkout Compose builds from is
+also mounted at `/opt/codeman`, so an update's `git checkout` and rebuild persist
+on the host, and the server exiting is what restarts the container onto the new
+build.
+
+Releases that change `server.Dockerfile`, `docker-compose.yaml`, or add a key to
+`.env.example` cannot be applied that way — the updater detects them, names what
+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.
+
+## Git commit identity
+
+Set `GIT_USER_NAME` and `GIT_USER_EMAIL` in `docker/.env` before rebuilding:
+
+```sh
+GIT_USER_NAME='Your Name'
+GIT_USER_EMAIL='you@example.com'
+```
+
+Compose passes the values to the Codeman server build, and to the server process
+when it builds Docker-case agent images. Both images write the pair to Git's
+system configuration during their build, so commits retain the same identity
+after a container or agent image is recreated. Set both values together; an
+image build with only one value fails rather than using a partial identity. An
+identity already present in `CODEMAN_APPDATA_PATH`'s `~/.gitconfig` overrides
+the server image's system-level default.
+
+Run `bash docker/Start-Codeman.sh` after changing the server values. Rebuild an
+existing agent image with `node scripts/build-agent-image.mjs --no-cache` in the
+server container, then recreate any Docker cases that should use it.
+
+## 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.
+
+`Start-Codeman.sh` names the Compose file explicitly, which disables Compose's automatic discovery of the override file, so the script adds it back when one is present and prints the file it used. Running `docker compose` from this folder without any `-f` option finds it automatically. When passing `-f docker/docker-compose.yaml` from the repository root, add `-f docker/docker-compose.override.yml` as well, or the override is silently ignored.
+
+An override file adds to and replaces individual settings. It cannot delete a key from `docker-compose.yaml`, and Compose concatenates rather than replaces `ports`, so removing a published port still requires editing `docker-compose.yaml`. The example below replaces the restart policy and adds a mount, leaving every other setting in place:
+
+```yaml
+services:
+  codeman:
+    restart: always
+    volumes:
+      - /srv/projects:/srv/projects
+```
+
+### Reverse-proxy host allowlist
+
+Codeman rejects any request whose `Host` header is not on its own allowlist - a
+DNS-rebinding guard, not a Compose or Docker concern. Loopback, any IP literal,
+the configured `--host`, and a few tunnel-provider suffixes are allowed by
+default; a reverse-proxied domain is not, and is rejected with
+`403 Forbidden: host not allowed` before the request reaches any handler.
+
+Add the domain with `CODEMAN_ALLOWED_HOSTS` in `.env`:
+
+```sh
+CODEMAN_ALLOWED_HOSTS='codeman.example.com,.internal.example.com'
+```
+
+`docker-compose.yaml` forwards it into the container (Compose only passes
+through the environment keys it explicitly lists, and this is one of them, with
+an empty default so the line is optional in `.env`).
+
+See the application's own `docs/wiki/Remote-Access.md` for the full allowlist
+format and the tunnel providers it accepts by default.
+
+## Application data storage
+
+The default configuration uses a host-folder bind mount:
+
+```yaml
+volumes:
+  - type: bind
+    source: ${CODEMAN_APPDATA_PATH}
+    target: /home/${CODEMAN_RUNTIME_USER}
+```
+
+Set `CODEMAN_APPDATA_PATH` in `.env` to a directory that the Docker daemon can access. The example value is `/mnt/user/appdata/codeman`.
+
+`CODEMAN_CASES_PATH` is the separate host directory for managed case workspaces. It is mounted into Codeman at the same absolute path, allowing the host Docker daemon to bind it into an isolated case container. Set it to a child directory of `CODEMAN_APPDATA_PATH` unless you deliberately store workspaces elsewhere.
+
+Compose also exposes `CODEMAN_APPDATA_PATH` to Codeman as `CODEMAN_DOCKER_HOST_HOME`. This lets Docker case seed files, CLI credentials and the hook secret be mounted using paths that exist in the host daemon's filesystem. Direct host installations do not set this variable and retain their existing behaviour.
+
+Set `CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=1` when `docker info` reports `SwapLimit=false`. Codeman continues to apply the configured case memory limit, omits Docker's unsupported `--memory-swap` option, and filters only the daemon's exact swap-capability warning. Every other Docker create error and its exit status remain visible.
+
+For an existing installation created by a root-running image, change ownership of the application-data directory before upgrading so the configured `PUID` and `PGID` can read the saved credentials and state:
+
+```sh
+chown -R 99:100 /mnt/user/appdata/codeman
+```
+
+Replace `99:100` and the path with the values from your `.env` file.
+
+Do not replace this bind mount with a Docker-managed named volume when Docker cases are enabled. Codeman passes seed, credential, transcript and hook-secret bind sources to the host Docker daemon, so their source files must have stable paths in the daemon's filesystem. A named volume does not provide the required host path mapping.
+
+## Static macvlan networking
+
+The default configuration publishes a host port. It does not use `network_mode: host`. To attach Codeman directly to an existing external macvlan network with a static IP address and MAC address, remove the `ports:` section from `docker-compose.yaml` and add the following to the `codeman` service. The service and network additions can instead be placed in `docker-compose.override.yml`, but the `ports:` removal cannot, as described under [Local customisation](#local-customisation):
+
+```yaml
+mac_address: ${CODEMAN_MAC_ADDRESS}
+networks:
+  codeman_lan:
+    ipv4_address: ${CODEMAN_IPV4_ADDRESS}
+```
+
+Then add this top-level network declaration:
+
+```yaml
+networks:
+  codeman_lan:
+    external: true
+    name: ${CODEMAN_MACVLAN_NETWORK}
+```
+
+Set `CODEMAN_MACVLAN_NETWORK`, `CODEMAN_IPV4_ADDRESS`, and `CODEMAN_MAC_ADDRESS` in `.env`. The values in `.env.example` match the supplied Unraid example network and should be changed for other hosts.
+
+### Create a managed macvlan network
+
+If an external macvlan network does not already exist, use this top-level declaration instead. Do not use it together with the external-network declaration.
+
+```yaml
+networks:
+  codeman_lan:
+    driver: macvlan
+    driver_opts:
+      parent: ${CODEMAN_MACVLAN_PARENT}
+    ipam:
+      config:
+        - subnet: ${CODEMAN_MACVLAN_SUBNET}
+          gateway: ${CODEMAN_MACVLAN_GATEWAY}
+```
+
+Macvlan containers are ordinarily not reachable from their Docker host without additional host-network routing. Confirm the selected address, MAC address, parent interface, and subnet are reserved and valid for the target network before starting the stack.

docker/Start-Codeman.sh

@@ -0,0 +1,309 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+script_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+env_file="$script_dir/.env"
+compose_file="$script_dir/docker-compose.yaml"
+
+if [[ ! -f "$env_file" ]]; then
+  printf 'Error: Docker environment file is missing: %s\n' "$env_file" >&2
+  printf 'Create it from %s/.env.example before starting Codeman.\n' "$script_dir" >&2
+  exit 1
+fi
+
+# Naming a Compose file explicitly disables Compose's automatic discovery of
+# the override file, so it has to be added back by hand. Without this, local
+# customisation in docker-compose.override.yml is silently ignored. The
+# candidates are checked in Compose's own precedence order - measured on
+# Compose 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[@]}")
+appdata_path=$(
+  "${compose_command[@]}" config --environment |
+    awk -F= '$1 == "CODEMAN_APPDATA_PATH" { sub(/^[^=]*=/, ""); print; exit }'
+)
+cases_path=$(
+  "${compose_command[@]}" config --environment |
+    awk -F= '$1 == "CODEMAN_CASES_PATH" { sub(/^[^=]*=/, ""); print; exit }'
+)
+docker_socket=$(
+  "${compose_command[@]}" config --environment |
+    awk -F= '$1 == "DOCKER_SOCKET" { sub(/^[^=]*=/, ""); print; exit }'
+)
+
+if [[ -z "$appdata_path" ]]; then
+  printf 'Error: CODEMAN_APPDATA_PATH is not set in %s\n' "$env_file" >&2
+  exit 1
+fi
+
+if [[ ! -d "$appdata_path" ]]; then
+  if [[ "$EUID" == '0' ]]; then
+    printf 'Error: Refusing to create CODEMAN_APPDATA_PATH as root: %s\n' "$appdata_path" >&2
+    printf 'Create it as the unprivileged account that should run Codeman, then retry.\n' >&2
+    exit 1
+  fi
+  mkdir -p -- "$appdata_path"
+fi
+
+if [[ -z "$cases_path" ]]; then
+  printf 'Error: CODEMAN_CASES_PATH is not set in %s\n' "$env_file" >&2
+  exit 1
+fi
+
+# `stat -c` is GNU, `stat -f` is BSD/macOS; the bind sources live on the Docker
+# host, so both need to work.
+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
+
+# Pre-creating this here, exactly like CODEMAN_APPDATA_PATH above, means Compose
+# never has to materialise a missing bind source itself - which it does as
+# root:root - so the in-container entrypoint's chown never has to run for this
+# path at all. It happens AFTER PUID/PGID are known (they come from the appdata
+# directory just above) so the new directory can be given that exact owner: a
+# plain `mkdir -p` lands as the invoking user's uid and PRIMARY gid, and on a
+# host set up the way the README suggests (`chown -R 99:100 <appdata>`) that gid
+# is not PGID, which the container would then refuse to run on. Unlike appdata,
+# an EXISTING cases directory is left exactly as it is: the README explicitly
+# allows pointing this at a normal projects directory the host account already
+# owns, and the container checks that it is WRITABLE as PUID:PGID rather than
+# who owns it.
+if [[ ! -d "$cases_path" ]]; then
+  mkdir -p -- "$cases_path"
+  if [[ "$(owner_of "$cases_path")" != "$PUID:$PGID" ]]; then
+    # As root this always succeeds; as a member of PGID a chgrp does; anyone
+    # else gets the clear error here, where the fix is obvious, rather than a
+    # restart loop from the container.
+    if ! chown -- "$PUID:$PGID" "$cases_path" 2>/dev/null; then
+      printf 'Error: created CODEMAN_CASES_PATH (%s) but could not make it %s:%s (the owner of CODEMAN_APPDATA_PATH).\n' \
+        "$cases_path" "$PUID" "$PGID" >&2
+      printf 'Run `chown %s:%s %s` as root, or create the directory as that account, then retry.\n' \
+        "$PUID" "$PGID" "$cases_path" >&2
+      exit 1
+    fi
+  fi
+fi
+
+if [[ -z "$docker_socket" || ! -S "$docker_socket" ]]; then
+  printf 'Error: DOCKER_SOCKET is not a Unix socket: %s\n' "${docker_socket:-<unset>}" >&2
+  exit 1
+fi
+
+if socket_ids=$(stat -c '%u:%g' -- "$docker_socket" 2>/dev/null); then
+  :
+elif socket_ids=$(stat -f '%u:%g' "$docker_socket" 2>/dev/null); then
+  :
+else
+  printf 'Error: Cannot determine the owner of DOCKER_SOCKET: %s\n' "$docker_socket" >&2
+  exit 1
+fi
+
+export DOCKER_SOCKET_GID=${socket_ids##*:}
+
+repo_path=${CODEMAN_REPO_PATH:-$(cd -- "$script_dir/.." && pwd)}
+if [[ ! -d "$repo_path" ]]; then
+  printf 'Error: CODEMAN_REPO_PATH is not a directory: %s\n' "$repo_path" >&2
+  exit 1
+fi
+export CODEMAN_REPO_PATH="$repo_path"
+
+# The in-app updater runs `git checkout` and `npm install` against this checkout
+# as PUID:PGID. If the directory belongs to someone else, git refuses outright
+# ("detected dubious ownership") and the update fails at the first step — so warn
+# here, where the fix is obvious, rather than in a failed update hours later.
+if repo_owner=$(stat -c '%u' -- "$repo_path" 2>/dev/null || stat -f '%u' "$repo_path" 2>/dev/null); then
+  if [[ "$repo_owner" != "$PUID" ]]; then
+    printf 'Warning: %s is owned by UID %s but Codeman runs as UID %s.\n' "$repo_path" "$repo_owner" "$PUID" >&2
+    printf 'In-app updates will fail until the ownership matches. Codeman itself still starts.\n' >&2
+  fi
+fi
+
+if [[ ! -d "$repo_path/.git" ]]; then
+  printf 'Note: %s is not a git checkout, so in-app updates are unavailable.\n' "$repo_path" >&2
+fi
+
+# Reads HEAD without requiring a `git` binary on the host — this script
+# otherwise checks the checkout only by testing for `.git` as a directory, and
+# resolving refs by hand keeps that the same "no host git needed" guarantee.
+# ⚠️ A worktree checkout has `.git` as a FILE (`gitdir: <path>`), not a
+# directory, so this returns nothing there and the volume-refresh check below
+# silently no-ops — consistent with the `-d .git` test used everywhere else in
+# this script, not a special case, but worth knowing if a worktree checkout
+# stops picking up a stale-volume refresh it should have caught.
+git_head_commit() {
+  local git_dir="$1/.git" head_ref ref_path
+  [[ -d "$git_dir" ]] || return 1
+  head_ref=$(cat -- "$git_dir/HEAD" 2>/dev/null) || return 1
+  if [[ "$head_ref" == ref:* ]]; then
+    ref_path="${head_ref#ref: }"
+    if [[ -f "$git_dir/$ref_path" ]]; then
+      cat -- "$git_dir/$ref_path"
+    else
+      # Packed after a `git gc`; the loose ref file above is gone.
+      awk -v ref="$ref_path" '$2 == ref { print $1; exit }' "$git_dir/packed-refs" 2>/dev/null
+    fi
+  else
+    printf '%s' "$head_ref"
+  fi
+}
+
+# Record what the container is about to be built and created FROM. The in-app
+# updater compares these against the release it wants to apply: a release that
+# changes either file cannot be applied by the container restarting itself (a
+# restart reuses the existing image and config), so it is refused and the user
+# is sent back here. Written on every start, so the baseline always describes
+# the container that is actually running. See docs/docker-self-update.md.
+if command -v sha256sum >/dev/null 2>&1; then
+  sha256_of() { sha256sum -- "$1" | cut -d' ' -f1; }
+elif command -v shasum >/dev/null 2>&1; then
+  sha256_of() { shasum -a 256 -- "$1" | cut -d' ' -f1; }
+else
+  sha256_of() { printf ''; }
+fi
+
+dockerfile_sha=$(sha256_of "$script_dir/server.Dockerfile")
+compose_sha=$(sha256_of "$compose_file")
+if [[ -n "$dockerfile_sha" && -n "$compose_sha" ]]; then
+  # $CODEMAN_APPDATA_PATH is mounted at the runtime account's home, so this is
+  # dataPath('docker-env-applied.json') as the server inside the container sees it.
+  state_dir="$appdata_path/.codeman"
+  mkdir -p -- "$state_dir"
+  printf '{\n  "dockerfileSha256": "%s",\n  "composeSha256": "%s"\n}\n' \
+    "$dockerfile_sha" "$compose_sha" >"$state_dir/docker-env-applied.json.tmp"
+  mv -- "$state_dir/docker-env-applied.json.tmp" "$state_dir/docker-env-applied.json"
+  # A root-run start (common on Unraid) would otherwise leave a root-owned
+  # `.codeman` on a FIRST start, before the container has created it as PUID,
+  # and the unprivileged server could then never write its own state there.
+  if [[ "$EUID" == '0' ]]; then
+    chown -- "$PUID:$PGID" "$state_dir" "$state_dir/docker-env-applied.json"
+  fi
+else
+  printf 'Warning: no sha256 tool found; in-app updates will not detect environment changes.\n' >&2
+fi
+
+# codeman-node-modules and codeman-dist (docker-compose.yaml) are seeded from
+# the image only while EMPTY, so a rebuilt image's fresh output sits unused
+# behind old volume content until something clears it. The in-app self-updater
+# never hits this — it rebuilds INSIDE the running container, into the very
+# volume already in use — but a `docker compose build` triggered from outside
+# it (this script, after a `git pull`) does: the container comes back up
+# looking unchanged. Detect that here and clear just the affected volume(s) so
+# the build below actually takes effect. Best-effort: with no sha256 tool this
+# quietly does nothing, same as the environment-gate block above.
+volumes_to_refresh=()
+if [[ -n "$dockerfile_sha" ]]; then
+  repo_head=$(git_head_commit "$repo_path" || true)
+  lockfile_sha=$(sha256_of "$repo_path/package-lock.json" 2>/dev/null || true)
+  source_state_file="$state_dir/docker-build-source.json"
+  prev_head=''
+  prev_lockfile_sha=''
+  if [[ -f "$source_state_file" ]]; then
+    prev_head=$(sed -n 's/.*"headCommit": *"\([^"]*\)".*/\1/p' "$source_state_file")
+    prev_lockfile_sha=$(sed -n 's/.*"lockfileSha256": *"\([^"]*\)".*/\1/p' "$source_state_file")
+  fi
+
+  [[ -n "$repo_head" && "$repo_head" != "$prev_head" ]] && volumes_to_refresh+=('codeman-dist')
+  [[ -n "$lockfile_sha" && "$lockfile_sha" != "$prev_lockfile_sha" ]] && volumes_to_refresh+=('codeman-node-modules')
+fi
+
+if [[ ${#volumes_to_refresh[@]} -eq 0 ]]; then
+  exec "${compose_command[@]}" up --build -d
+fi
+
+# Runs even on this script's very first invocation against an EXISTING
+# deployment, deliberately: that deployment's volumes may already be stale
+# (there was no earlier version of this check to have caught it), and clearing
+# an already-empty or nonexistent volume is a harmless no-op, so there is no
+# fresh-install case this needs to avoid.
+printf 'Source changed since the last start; refreshing: %s\n' "${volumes_to_refresh[*]}"
+
+# Build BEFORE taking the stack down: the image build is the slow part and needs
+# no container stopped, so the deployment is offline only for the recreate.
+"${compose_command[@]}" build
+
+# `com.docker.compose.volume` is the volume KEY, not a project-qualified name -
+# a second stack on the same host (a beta instance started with a different
+# COMPOSE_PROJECT_NAME, say) that also declares a volume keyed `codeman-dist`
+# shares that label, and `head -n1` would pick whichever the daemon happens to
+# list first. Scope the lookup to THIS stack's own resolved project name so it
+# can only ever match this stack's volume. The name is read from the resolved
+# config's top-level `name` key, indentation-agnostic (the formatting is not a
+# contract), and the FIRST `name` in the output is the project's: nested ones
+# (a network's `name:`) come later. `--format json` needs Compose v2.3+.
+project_name=$(
+  "${compose_command[@]}" config --format json 2>/dev/null |
+    sed -n 's/^[[:space:]]*"name":[[:space:]]*"\([^"]*\)".*$/\1/p' | head -n1
+)
+
+"${compose_command[@]}" down
+
+# Track whether the volumes were actually cleared. The marker below is written
+# ONLY on success: with an unresolvable project name the label filter would
+# match nothing, nothing would be removed, and a marker recording the new HEAD
+# would stop this check from ever firing again while the stale volume kept
+# serving old code. A failed removal likewise leaves the marker alone, so the
+# next start retries, and the stack is brought back up regardless rather than
+# left down.
+refreshed=1
+if [[ -z "$project_name" ]]; then
+  # The documented reset (docs/docker-self-update.md): both volumes re-seed from
+  # the image by a plain copy, so clearing the extra one costs a copy, not data.
+  printf 'Warning: could not resolve the Compose project name; clearing both build-artefact volumes with `down --volumes` instead.\n' >&2
+  "${compose_command[@]}" down --volumes || refreshed=0
+else
+  for key in "${volumes_to_refresh[@]}"; do
+    volume_name=$(
+      docker volume ls -q \
+        --filter "label=com.docker.compose.volume=$key" \
+        --filter "label=com.docker.compose.project=$project_name" |
+        head -n1
+    )
+    if [[ -n "$volume_name" ]] && ! docker volume rm -- "$volume_name"; then
+      printf 'Warning: could not remove volume %s; it will be retried on the next start.\n' "$volume_name" >&2
+      refreshed=0
+    fi
+  done
+fi
+
+if [[ "$refreshed" == '1' ]]; then
+  printf '{\n  "headCommit": "%s",\n  "lockfileSha256": "%s"\n}\n' \
+    "$repo_head" "$lockfile_sha" >"$source_state_file.tmp"
+  mv -- "$source_state_file.tmp" "$source_state_file"
+  if [[ "$EUID" == '0' ]]; then
+    chown -- "$PUID:$PGID" "$source_state_file"
+  fi
+else
+  printf 'Warning: the build-artefact volumes were NOT refreshed; the container may serve stale code until the next successful start.\n' >&2
+fi
+
+# Already built above, so no --build here: a second build would only re-check
+# the cache.
+exec "${compose_command[@]}" up -d

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

@@ -17,6 +17,7 @@ FROM node:22-bookworm-slim
 RUN apt-get update \
  && apt-get install -y --no-install-recommends \
       git \
+      libsecret-1-0 \
       tmux \
       ripgrep \
       curl \
@@ -26,15 +27,182 @@ RUN apt-get update \
       openssh-client \
  && rm -rf /var/lib/apt/lists/*
 
-# The agent CLIs (all four backends Codeman supports). Pinning is left to the
-# rebuild cadence (see docs/docker-cases-plan.md, user-decision 2).
-RUN npm install -g \
-      @anthropic-ai/claude-code \
-      @openai/codex \
-      @google/gemini-cli \
-      opencode-ai \
+# 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.
+#
+# ⚠️ Expanded UNQUOTED on purpose: word splitting is what turns the list into
+# several arguments. Every token is validated against
+# ^[@A-Za-z0-9][@A-Za-z0-9/._-]*$ on the producing side
+# (scripts/lib/cli-catalog.mjs) precisely because of that.
+#
+# ⚠️ Filtered on each entry's `enabled` flag, so a CLI that ships disabled is
+# never baked into every image.
+#
+# Pinning is left to the rebuild cadence (see docs/docker-cases-plan.md,
+# user-decision 2).
+# ⚠️ The default is in REGISTRY order, byte-identical to what the generator emits.
+# A different order is a different RUN string, which is a different layer hash and
+# so a needless cache miss between a bare `docker build` and a scripted one.
+ARG CLI_NPM_PACKAGES="@anthropic-ai/claude-code opencode-ai @openai/codex @google/gemini-cli"
+# uv/uvx: MCP servers are commonly launched with `uvx <package>` (e.g. the Nginx
+# Proxy Manager MCP), and Codex failed to enable them with "uvx not found". Copied
+# from the pinned upstream image into root-owned /usr/local/bin, never pip-installed.
+COPY --from=ghcr.io/astral-sh/uv:0.9 /uv /uvx /usr/local/bin/
+RUN npm install -g ${CLI_NPM_PACKAGES} \
  && npm cache clean --force
 
+# Antigravity (`agy`) is NOT on npm — Google ships a standalone binary through its
+# own installer, so it needs its own step. `--dir /usr/local/bin` is load-bearing:
+# the installer's default target is `$HOME/.local/bin`, which at build time is
+# root's home and would be unreachable by the `agent` user the container runs as.
+# ⚠️ This binary is ~190MB on its own; it is the single largest layer in the image.
+RUN curl -fsSL https://antigravity.google/cli/install.sh | bash -s -- --dir /usr/local/bin \
+ && chmod 755 /usr/local/bin/agy \
+ && agy --version
+
+# Pi (pi.dev). Upstream documents --ignore-scripts (pi needs no lifecycle scripts);
+# kept out of the shared npm block above so the flag cannot silently change how the
+# rest of that block's CLIs install — a fixed count would go stale here since
+# CLI_NPM_PACKAGES (above) is now a generated, dynamic list rather than a hand-kept one.
+RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent \
+ && npm cache clean --force \
+ && pi --version
+
+# Grok Build (`grok`, xAI) is NOT on npm: a standalone ~160MB Rust binary through
+# xAI's installer, which targets $HOME/.grok/bin with no --dir override. At build
+# time that is root's home and unreachable by the `agent` user, so copy the binary
+# into /usr/local/bin and drop root's ~/.grok in the same layer so the image does
+# not carry the download twice. The staging cp -T is what makes this survive the
+# installer's own behavior EITHER way: newer installers already symlink
+# /usr/local/bin/grok -> /root/.grok/bin/grok, and a direct `cp -L` onto that
+# symlink fails with "same file" (2026-08-24 rebuild), while removing the link
+# first and copying fresh works for both old and new installers.
+RUN curl -fsSL https://x.ai/cli/install.sh | bash \
+ && cp -L /root/.grok/bin/grok /usr/local/bin/grok.real \
+ && rm -f /usr/local/bin/grok \
+ && mv /usr/local/bin/grok.real /usr/local/bin/grok \
+ && chmod 755 /usr/local/bin/grok \
+ && rm -rf /root/.grok /root/.local/bin/grok /root/.local/bin/agent \
+ && grok --version
+
+# DeepSeek Harness (`dsh`). A normal npm package, but the ONLY entry here whose
+# binary runs nothing on its own: `dsh` is a profile launcher, and DeepSeek ships
+# only `web` and `headless`, so without an interactive profile a
+# `mode: 'deepseek'` container would start a pane that dies on arrival. The
+# profile itself is installed further down, into the `agent` HOME, because
+# Codeman deliberately does NOT seed `profiles/` from the host: it is a
+# per-profile node_modules tree, host-arch-specific and far too large to copy on
+# every container start.
+# ⚠️ `pnpm` is a HARD dependency of `dsh plugin`, not optional tooling: the
+# subcommand is a thin forwarder that `spawnSync`s a literal `pnpm` with no
+# fallback to npm, so on an image without it the profile install below dies
+# with `dsh: pnpm not found on PATH` / exit 127 and takes the whole build with
+# it (issue #352). It stays on PATH at runtime too, so a container user can run
+# `dsh plugin add` themselves.
+RUN npm install -g @deepseek-ai/dsh pnpm \
+ && npm cache clean --force \
+ && dsh --version \
+ && pnpm --version
+
+# OMP (Oh My Pi) is NOT on npm: a standalone binary via omp.sh's installer, which
+# targets $HOME/.local/bin with no --dir override (verified 2026-08-27 — the
+# resolver's OMP_SEARCH_DIRS lists ~/.omp/bin first, which turned out to be the
+# WRONG guess for the installer's actual target; build this step for real
+# rather than trust that ordering). At build time $HOME is root's home and
+# unreachable by the `agent` user, so copy the binary into /usr/local/bin and
+# drop root's ~/.local/bin/omp in the same layer so the image does not carry
+# the download twice.
+RUN curl -fsSL https://omp.sh/install | sh \
+ && cp -L /root/.local/bin/omp /usr/local/bin/omp.real \
+ && rm -f /usr/local/bin/omp \
+ && mv /usr/local/bin/omp.real /usr/local/bin/omp \
+ && chmod 755 /usr/local/bin/omp \
+ && rm -f /root/.local/bin/omp \
+ && omp --version
+
 # `agent` user (gid 0) with an arbitrary-uid-writable HOME. The uid is
 # auto-assigned (node:22-slim already occupies uid 1000 with its `node` user); at
 # runtime Codeman overrides with `--user <hostUid>:0` on Linux, so the baked uid
@@ -50,13 +218,57 @@ ENV HOME=/home/agent
 # dirs: tokens/settings/config are seeded in as writable copies and each CLI's runtime
 # state (backups, tasks, refreshed tokens) stays container-local, while ONLY the shared
 # transcript/rollout dirs (`.claude/projects`, `.codex/sessions`) are bind-mounted from
-# the host. (gemini/gcloud/opencode are whole seed-copies and need no pre-created dir.)
+# the host. (gemini/gcloud/opencode are whole seed-copies and need no pre-created dir;
+# Antigravity nests its state inside `.gemini/antigravity-cli`, so it rides that seed.)
+# `.pi/agent` and `.grok` ARE pre-created: both are seeded per-FILE (pi:
+# auth/settings/trust/models; grok: auth.json/config.toml/pager.toml), and a
+# per-file seed copy, unlike a whole-dir one, does not create its parent directory.
+# `.dsh` is pre-created for the same per-file reason (.env/settings.yaml/
+# cordis.patch.yml), and the interactive profile is built into it HERE rather than
+# after `USER agent`: this layer's closing chgrp/chmod is what makes the whole tree
+# writable by the arbitrary uid the container actually runs as, and a profile
+# installed after it would miss that fixup. DSH_HOME points the launcher at the
+# agent's dir while this still runs as root.
+# ⚠️ `dangerouslyAllowAllBuilds` is what keeps that profile install from becoming
+# the next #352. pnpm (unlike npm) blocks dependency lifecycle scripts by default
+# and FAILS the install over it — `ERR_PNPM_IGNORED_BUILDS`, exit 1, measured on
+# pnpm 11.24 — so any package in the tui's tree that ships one stops the build
+# dead. An allowlist of the offenders rots: `@deepseek-harness-tui/dsh-tui` is
+# resolved by dist-tag, not pinned, and 0.9.3 pulled `@google/genai` (a
+# `preinstall: no-op`) where 0.10.0-beta.x does not, so the names to allow move
+# under us between rebuilds. Allowing them wholesale is also the SAME exposure
+# this image already accepts three layers up: `npm install -g` runs the install
+# scripts of every transitive dep of the five CLIs above it, with no gate at all.
+# `.omp/agent` is pre-created for the same reason `.codex` is: it is a MIXED
+# store (per-file config seeds PLUS a shared `sessions/` RW bind mount for
+# Codeman's own host-side history/resume reads), and neither kind of artifact
+# creates its own parent directory.
 RUN useradd -g 0 -m -d /home/agent -s /bin/bash agent \
  && mkdir -p /home/agent/.npm /home/agent/.cache /home/agent/.config /home/agent/.codeman \
-      /home/agent/.claude/projects /home/agent/.codex/sessions \
+      /home/agent/.claude/projects /home/agent/.codex/sessions /home/agent/.pi/agent /home/agent/.grok \
+      /home/agent/.dsh /home/agent/.omp/agent \
+ && DSH_HOME=/home/agent/.dsh HOME=/home/agent \
+      dsh plugin --profile dsh-tui add --config.dangerouslyAllowAllBuilds=true \
+      @deepseek-harness-tui/dsh-tui \
+ && test -f /home/agent/.dsh/profiles/dsh-tui/package.json \
  && chgrp -R 0 /home/agent \
  && chmod -R g=u /home/agent
 
+# Docker cases have a fresh, container-owned home directory. Declare the
+# optional identity here so changing it invalidates only this final layer, then
+# configure Git's system defaults. A user-level config still takes precedence.
+ARG GIT_USER_EMAIL=
+ARG GIT_USER_NAME=
+RUN set -eux; \
+    if [ -n "${GIT_USER_NAME}" ] || [ -n "${GIT_USER_EMAIL}" ]; then \
+      if [ -z "${GIT_USER_NAME}" ] || [ -z "${GIT_USER_EMAIL}" ]; then \
+        echo 'Git user name and email must both be set when configuring Git identity' >&2; \
+        exit 1; \
+      fi; \
+      git config --system user.name "${GIT_USER_NAME}"; \
+      git config --system user.email "${GIT_USER_EMAIL}"; \
+    fi
+
 USER agent
 WORKDIR /home/agent
 

docker/docker-compose.yaml

@@ -0,0 +1,138 @@
+name: codeman
+
+services:
+  codeman:
+    build:
+      context: ..
+      dockerfile: docker/server.Dockerfile
+      args:
+        CODEMAN_RUNTIME_USER: ${CODEMAN_RUNTIME_USER}
+        GIT_USER_EMAIL: ${GIT_USER_EMAIL:-}
+        GIT_USER_NAME: ${GIT_USER_NAME:-}
+        PGID: ${PGID:-1000}
+        PUID: ${PUID:-1000}
+    image: ${CODEMAN_IMAGE}
+    init: true
+    restart: unless-stopped
+    ports:
+      - "${CODEMAN_PORT}:${CODEMAN_PORT}"
+    environment:
+      # Tells the self-updater to restart by exiting (the restart policy below
+      # relaunches it) rather than by looking for an init system that is not
+      # here. Also set in the image; repeated so a container started without the
+      # image default still self-identifies.
+      CODEMAN_IN_CONTAINER: "1"
+      # This file sets `restart: unless-stopped` below, so the updater may restart
+      # the server by EXITING. Declared here and only here, never in the image: a
+      # container started by plain `docker run` has no restart policy unless the
+      # operator gave it one, and there the updater asks the daemon instead and
+      # stages the update for a manual restart when it cannot get an answer.
+      CODEMAN_RESTART_BY_EXIT: "1"
+      CODEMAN_DOCKER_BRIDGE_HOOKS: ${CODEMAN_DOCKER_BRIDGE_HOOKS}
+      # Host-side equivalent of the runtime user's HOME. Docker case seed,
+      # credential and hook mounts are translated into the daemon namespace.
+      CODEMAN_DOCKER_HOST_HOME: ${CODEMAN_APPDATA_PATH}
+      CODEMAN_DOCKER_DISABLE_SWAP_LIMIT: ${CODEMAN_DOCKER_DISABLE_SWAP_LIMIT}
+      CODEMAN_CASES_PATH: ${CODEMAN_CASES_PATH}
+      # Passed through only so Codeman can use the same identity when it builds
+      # the Docker-case agent image.
+      CODEMAN_AGENT_IMAGE_GIT_USER_EMAIL: ${GIT_USER_EMAIL:-}
+      CODEMAN_AGENT_IMAGE_GIT_USER_NAME: ${GIT_USER_NAME:-}
+      # Extra Host-header allowlist entries for a reverse-proxied deployment
+      # (docker/README.md, "Reverse-proxy host allowlist"). Optional, so it
+      # defaults to empty rather than requiring a line in every .env.
+      CODEMAN_ALLOWED_HOSTS: ${CODEMAN_ALLOWED_HOSTS:-}
+      CODEMAN_HOST: ${CODEMAN_HOST}
+      CODEMAN_PASSWORD: ${CODEMAN_PASSWORD}
+      CODEMAN_PORT: ${CODEMAN_PORT}
+      CODEMAN_USERNAME: ${CODEMAN_USERNAME}
+      GEMINI_API_KEY: ${GEMINI_API_KEY}
+      PGID: ${PGID:-1000}
+      PUID: ${PUID:-1000}
+      TZ: ${TZ}
+    group_add:
+      # Retain access to the host Docker socket without running as root.
+      - ${DOCKER_SOCKET_GID:-999}
+    volumes:
+      # Application data and CLI credentials persist on the configured host
+      # path, rather than in a Docker-managed volume.
+      - type: bind
+        source: ${CODEMAN_APPDATA_PATH}
+        target: /home/${CODEMAN_RUNTIME_USER}
+      # Docker cases are sibling containers on the host daemon. Their workspace
+      # must be visible to Codeman at the same absolute path used by that daemon.
+      - type: bind
+        source: ${CODEMAN_CASES_PATH}
+        target: ${CODEMAN_CASES_PATH}
+      # Codeman uses the host daemon to create isolated Docker cases. This is
+      # Docker-outside-of-Docker, not Docker-in-Docker.
+      - type: bind
+        source: ${DOCKER_SOCKET}
+        target: /var/run/docker.sock
+      # The application source, so App Settings -> Updates can update in place.
+      # This is the SAME checkout used as the build context above, mounted over
+      # the image's baked copy: a `git checkout` performed inside the container
+      # then lands on the host and survives the container being recreated.
+      # Without it the pull would go to the container's writable layer and be
+      # silently discarded by the next `up`. See docs/docker-self-update.md.
+      # Defaults to `..` — the build context above — which Compose resolves
+      # against the project directory, so plain `docker compose up` works with
+      # no extra configuration. Set CODEMAN_REPO_PATH only to point elsewhere.
+      - type: bind
+        source: ${CODEMAN_REPO_PATH:-..}
+        target: /opt/codeman
+      # Build artefacts live in named volumes layered OVER the repo bind mount,
+      # so `npm install` and `npm run build` inside the container never write
+      # into the host checkout. That keeps container-compiled native modules
+      # (node-pty is built from source here) out of a checkout that may also be
+      # used to run Codeman natively, and keeps `git status` clean. Docker seeds
+      # an EMPTY named volume from the image, so the first start inherits the
+      # image's already-built node_modules and dist rather than paying for a
+      # bootstrap build.
+      - type: volume
+        source: codeman-node-modules
+        target: /opt/codeman/node_modules
+      - type: volume
+        source: codeman-dist
+        target: /opt/codeman/dist
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    cap_add:
+      # The entrypoint corrects bind-mount ownership as root before dropping to
+      # PUID:PGID. Everything not listed here remains dropped by cap_drop above.
+      # test/docker-entrypoint.test.ts pins this list against what the
+      # entrypoint and `init: true` actually need, so a capability cannot go
+      # missing silently again.
+      - CHOWN
+      - DAC_OVERRIDE
+      # `init: true` makes tini PID 1, and tini stays ROOT while the entrypoint
+      # drops the server to PUID. Signalling a process of a different uid needs
+      # CAP_KILL; without it tini's SIGTERM forward fails ("Unexpected error
+      # when forwarding signal: 'Operation not permitted'"), tini dies, and the
+      # PID namespace teardown SIGKILLs the server instead of letting
+      # `server.stop()` flush state on every `docker compose down`/`restart`.
+      - KILL
+      - SETGID
+      - SETUID
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - >-
+          node -e "fetch('http://127.0.0.1:${CODEMAN_PORT}/api/status').then((response) => process.exit(response.status < 500 ? 0 : 1)).catch(() => process.exit(1))"
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+
+volumes:
+  # Container-owned build artefacts. They persist across container recreation,
+  # so an in-app update's `npm install` output is not thrown away by the next
+  # `up`, and they are seeded from the image on first use. Removing them (or
+  # `docker compose down -v`) is the supported reset: the next start rebuilds
+  # from the image.
+  codeman-node-modules:
+  codeman-dist:

docker/entrypoint.sh

@@ -0,0 +1,165 @@
+#!/bin/sh
+# Corrects ownership - host bind mounts, and the image-baked CLI prefix -
+# then drops to PUID:PGID.
+#
+# Compose binds CODEMAN_APPDATA_PATH and CODEMAN_CASES_PATH from the host. When
+# either path does not exist yet - a first run, a cleared application-data
+# directory, a restored backup - the Docker daemon creates it owned by root,
+# and an unprivileged server cannot then create its own state directory. The
+# result is a container that restarts forever on:
+#
+#   Failed to start web server: EACCES: permission denied, mkdir '/home/<user>/.codeman'
+#
+# Running this as root and dropping afterwards removes that failure mode without
+# leaving the server privileged. The same root start also lets it re-assert
+# /opt/codeman-cli's ownership on every start, not just at image build time -
+# see the comment at that chown below for why that matters for anyone who
+# runs the compose file directly rather than through Start-Codeman.sh.
+#
+# Capabilities this script needs against the compose file's `cap_drop: ALL`
+# (test/docker-entrypoint.test.ts pins the list against docker-compose.yaml):
+#   CHOWN + DAC_OVERRIDE  the chown of a root-owned bind source below
+#   SETUID + SETGID       the setpriv drop itself
+#   KILL                  NOT used here, but required by the container: with
+#                         `init: true` tini is PID 1 and runs as root while the
+#                         server runs as PUID, and signalling a process of a
+#                         different uid needs CAP_KILL. Without it every
+#                         `docker compose down`/`restart` ends in tini dying with
+#                         "Unexpected error when forwarding signal" and the
+#                         server being SIGKILLed instead of stopping cleanly.
+
+set -eu
+
+# Honour an explicit `user:` in Compose: when the container was not started as
+# root there is nothing to correct and no privilege to drop.
+if [ "$(id -u)" -ne 0 ]; then
+  exec "$@"
+fi
+
+# Everything below runs as root and calls stat, chown, id, setpriv and friends
+# by bare name, so the lookup path must not contain a directory the runtime
+# account can write to. /opt/codeman-cli/bin is exactly that (it is chowned to
+# PUID:PGID so sessions can update the agent CLIs in place), and the image
+# appends it to PATH for the server's sake. Resolve root's commands through the
+# system directories only, and hand the image's full PATH back to the server at
+# the exec below, since Codeman resolves the agent CLIs through it.
+runtime_path=$PATH
+PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+export PATH
+
+: "${PUID:=1000}"
+: "${PGID:=1000}"
+
+# The capabilities the compose file must grant, named in the diagnosis below so
+# an out-of-tree compose file (Unraid's Compose Manager, a hand-written unit)
+# fails with a one-line fix instead of a restart loop.
+required_caps='CHOWN, DAC_OVERRIDE, KILL, SETGID, SETUID'
+
+# Pre-flight the drop itself before touching anything. A container started with
+# `cap_drop: ALL` and none of the additions above fails here, and would otherwise
+# die at the final exec with a bare "setpriv: setresuid failed: Operation not
+# permitted" after chown had already failed, or worse, misreport a perfectly
+# writable directory as unwritable because the probe below could not drop
+# privileges to test it.
+if ! setpriv --reuid "$PUID" --regid "$PGID" --clear-groups true 2>/dev/null; then
+  printf 'entrypoint: cannot drop privileges to PUID:PGID (%s:%s).\n' "$PUID" "$PGID" >&2
+  printf 'entrypoint: this image starts as root and drops with setpriv, which needs\n' >&2
+  printf 'entrypoint:   cap_add: [%s]\n' "$required_caps" >&2
+  printf 'entrypoint: on top of cap_drop: ALL (see docker/docker-compose.yaml). Add them to the\n' >&2
+  printf 'entrypoint: compose file that started this container, or set `user:` to skip the drop entirely.\n' >&2
+  exit 1
+fi
+
+# Preserve the supplementary groups Compose granted through group_add - that is
+# how the Docker socket stays reachable - while discarding root's own group.
+supplementary=$(id -G | tr ' ' '\n' | grep -vx 0 | paste -sd, -)
+[ -n "$supplementary" ] || supplementary="$PGID"
+
+# Writable as the account the server is about to become? A real probe, run as
+# exactly the identity the final exec below produces (PUID, PGID, the same
+# supplementary groups, capabilities dropped), rather than a comparison of
+# owners: ownership is not writability. A group-writable tree owned by another
+# account, an ACL, or a CIFS/NFS mount that reports some unrelated uid are all
+# fine to run on and would all fail an owner check.
+writable_as_runtime() {
+  setpriv --reuid "$PUID" --regid "$PGID" --groups "$supplementary" test -w "$1" 2>/dev/null
+}
+
+for target in "${HOME:-}" "${CODEMAN_CASES_PATH:-}"; do
+  [ -n "$target" ] && [ -d "$target" ] || continue
+  owner=$(stat -c '%u:%g' "$target")
+  [ "$owner" = "${PUID}:${PGID}" ] && continue
+
+  # Only ever correct a directory the DAEMON created: root-owned, because
+  # neither PUID nor PGID existed yet when it materialised the missing bind
+  # source. Anything else - a host tree that legitimately belongs to some
+  # OTHER account, such as an existing CODEMAN_CASES_PATH the README already
+  # allows pointing at a normal project directory - is not this container's
+  # to reassign; recursively chowning it on every mismatch silently rewrote
+  # a credentials tree or a projects directory to PUID:PGID with one log
+  # line to explain it. Such a directory is left alone and only PROBED below.
+  #
+  # The chown is deliberately not fatal. A bind mount backed by NFS, CIFS or a
+  # rootless daemon can refuse chown while still being perfectly writable, and
+  # the probe below is what decides whether the server can run on it.
+  if [ "${owner%%:*}" = '0' ]; then
+    if chown -R "${PUID}:${PGID}" "$target" 2>/dev/null; then
+      printf 'entrypoint: corrected ownership of %s to %s:%s\n' "$target" "$PUID" "$PGID"
+    else
+      printf 'entrypoint: warning: cannot change ownership of %s to %s:%s; checking whether it is writable anyway\n' \
+        "$target" "$PUID" "$PGID" >&2
+    fi
+  fi
+
+  if writable_as_runtime "$target"; then
+    if [ "${owner%%:*}" != '0' ]; then
+      printf 'entrypoint: %s is owned by %s, not %s:%s, but is writable as the runtime account; leaving its ownership alone\n' \
+        "$target" "$owner" "$PUID" "$PGID"
+    fi
+    continue
+  fi
+
+  printf 'entrypoint: %s is not writable as PUID:PGID (%s:%s); it is owned by %s.\n' \
+    "$target" "$PUID" "$PGID" "$owner" >&2
+  printf 'entrypoint: refusing to change ownership of a directory this container did not create.\n' >&2
+  printf 'entrypoint: either chown it on the host, make it writable to %s:%s, or set PUID/PGID to match its owner.\n' \
+    "$PUID" "$PGID" >&2
+  exit 1
+done
+
+# /opt/codeman-cli (the four agent CLIs) is chowned to PUID:PGID once, at
+# image BUILD time, from the PUID/PGID build args - server.Dockerfile's own
+# comment on that RUN step explains why it lives in its own prefix rather than
+# /usr/local. Unlike HOME/CODEMAN_CASES_PATH above, that bake happens only
+# when the image is actually rebuilt (`docker compose up --build`, which
+# Start-Codeman.sh always does) - a deployment that instead runs the compose
+# file directly (Unraid's Compose Manager, a native Debian systemd unit, any
+# `docker compose up`/`restart` with no --build) can change PUID/PGID in .env
+# and restart without ever rebuilding, at which point the container runs as
+# the NEW uid while the CLI directory is still owned by the OLD one baked into
+# the image layer - silently breaking the very "self-update a CLI in place"
+# fix this directory exists for. Re-assert it here, every start, unconditionally:
+# unlike the host bind mounts above, this is pure image content Codeman itself
+# populated, never host data that might legitimately belong to someone else,
+# so there is no ownership to be careful about - it is always correct for it
+# to be owned by whoever this container is about to run as.
+if [ -d /opt/codeman-cli ] && [ "$(stat -c '%u:%g' /opt/codeman-cli)" != "${PUID}:${PGID}" ]; then
+  chown -R "${PUID}:${PGID}" /opt/codeman-cli
+fi
+
+# Discarding group 0 is right for root's own group, but it also discards a
+# `group_add: 0` that was there to reach a Docker socket owned by root:root.
+# The previous image ran as PUID with that group kept, so say so rather than
+# letting Docker-case support vanish silently on such a host.
+if [ -S /var/run/docker.sock ] && [ "$(stat -c '%g' /var/run/docker.sock)" = '0' ]; then
+  printf 'entrypoint: warning: /var/run/docker.sock is owned by group 0, which is dropped along with root;\n' >&2
+  printf 'entrypoint: warning: Docker cases will not work from this container. Give the socket a dedicated\n' >&2
+  printf 'entrypoint: warning: group on the host and set DOCKER_SOCKET_GID to it.\n' >&2
+fi
+
+# No `--bounding-set -all` here: it is a silent no-op without CAP_SETPCAP, which
+# the compose file deliberately does not grant, and `no-new-privileges` already
+# makes the bounding set moot. The reuid/regid drop leaves CapPrm/CapEff empty.
+# The image's full PATH goes back to the server here; see the top of the file.
+exec setpriv --reuid "$PUID" --regid "$PGID" --groups "$supplementary" \
+  env PATH="$runtime_path" "$@"

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

@@ -0,0 +1,322 @@
+# syntax=docker/dockerfile:1
+
+# Build the application from the checkout supplied as the Docker build context.
+# No published Codeman application image is required.
+FROM node:22-bookworm-slim AS build
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends python3 make g++ \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /opt/codeman
+
+COPY . .
+
+# devDependencies are deliberately KEPT (no `npm prune --omit=dev`). The in-app
+# updater rebuilds from inside this container, and `npm run build` is tsc +
+# esbuild — both devDependencies. Pruning them saves image size and takes the
+# self-updater with it. See docs/docker-self-update.md.
+RUN npm ci \
+ && npm run build \
+ && npm cache clean --force
+
+# The Docker CLI talks to the host daemon through the socket mounted by
+# docker/docker-compose.yaml. It does not run a Docker daemon in this container.
+FROM node:22-bookworm-slim
+
+ARG CODEMAN_RUNTIME_USER=codeman
+ARG PUID=1000
+ARG PGID=1000
+
+# python3/make/g++ are here for the SELF-UPDATER, not for this build. An update
+# runs `npm install` inside the running container, and node-pty ships no Linux
+# prebuild, so a release that bumps it compiles from source right here. Without
+# a toolchain that install fails and the update rolls back — every time, on the
+# releases that need it most. Same reason install.sh installs one on bare hosts.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+      ca-certificates \
+      curl \
+      g++ \
+      git \
+      libsecret-1-0 \
+      make \
+      openssh-client \
+      procps \
+      python3 \
+      ripgrep \
+      tmux \
+ && rm -rf /var/lib/apt/lists/*
+
+# The Docker CLI, taken from the official image rather than Debian's `docker.io`.
+# That package is the full ENGINE: with --no-install-recommends it still pulls 15
+# packages including containerd, runc, dmsetup and iptables, none of which a
+# client that only talks to a mounted socket can use. Measured on top of this
+# base image: `docker.io` costs 266 MB and ships Docker 20.10.24 (2023), while
+# these two files cost 108 MB and ship the current CLI (493 MB vs 335 MB total).
+#
+# The binaries are STATIC Go builds, so they run on this glibc image even though
+# the image they come from is Alpine (verified: `docker --version`, `docker ps`
+# and `docker build` all work here against a mounted host socket).
+#
+# buildx is copied on purpose. `scripts/build-agent-image.mjs` shells out to
+# `docker build` — Codeman auto-builds the agent image on the first Docker case —
+# and without the plugin that silently falls back to the CLASSIC builder, which
+# Docker has deprecated and will eventually drop. `docker-compose` is NOT copied:
+# Codeman never shells out to it.
+COPY --from=docker:29-cli /usr/local/bin/docker /usr/local/bin/docker
+COPY --from=docker:29-cli \
+     /usr/local/libexec/docker/cli-plugins/docker-buildx \
+     /usr/local/libexec/docker/cli-plugins/docker-buildx
+
+# 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.
+#
+# Installed into a DEDICATED prefix, /opt/codeman-cli, not the base image's
+# default /usr/local. A session needs write access to wherever these CLIs live
+# so it can self-update one in place (observed via Codex's own
+# `npm install -g @openai/codex`, which renames the old package directory
+# aside before installing the new one — a rename needs write access to the
+# PARENT directory, not just the target, so the runtime account needs that
+# access at the directory level). Chowning /usr/local/bin and
+# /usr/local/lib/node_modules directly to get it would ALSO hand away
+# entrypoint.sh (COPY'd to /usr/local/bin below, root-owned, executed as root
+# on every container start with CHOWN/DAC_OVERRIDE/SETUID/SETGID) and the node
+# binary: owning the DIRECTORY is enough to rename it aside and drop a
+# replacement, even though the file itself stays root-owned, which would let a
+# compromised session arrange for its own script to run as root at the next
+# restart — undoing the "the server itself never runs privileged" guarantee
+# the entrypoint exists to provide. /opt/codeman-cli holds nothing else to
+# escalate through, so owning it is exactly the CLI-update access it needs and
+# no more.
+#
+# ⚠️ PINNED ON PURPOSE. Unpinned, the agent CLI versions a user ends up with are
+# a function of WHEN their image was built, not of any commit — so a Codeman
+# release that depends on newer CLI behaviour (the trust-dialog handling is
+# pinned to Claude Code 2.1.252's layout; wheel forwarding to >= 2.1.187) breaks
+# on an older image with no diff anywhere to explain why. In-app updates make
+# rebuilds RARER, which makes that drift worse. Pinning turns "this release needs
+# a newer CLI" into a Dockerfile change, which the updater's environment gate
+# already detects and refuses (docs/docker-self-update.md).
+#
+# Bump these deliberately, in a release. `--no-cache` is still needed to rebuild
+# this layer when only the pins change upstream.
+# The prefix is APPENDED to PATH, never prepended: it is chowned to the runtime
+# account below, and entrypoint.sh runs as root calling stat/chown/setpriv by
+# bare name. A prefix ahead of /usr/bin would let a session drop a `setpriv`
+# there and have it run as root at the next container start (measured with a
+# minimal image of this exact shape). The four CLIs live only in this prefix,
+# so they still resolve; entrypoint.sh additionally pins its own PATH to the
+# system directories for the root part of the start.
+# uv/uvx: MCP servers are commonly launched with `uvx <package>` (e.g. the Nginx
+# Proxy Manager MCP), and Codex failed to enable them with "uvx not found". Copied
+# from the pinned upstream image into root-owned /usr/local/bin, never pip-installed.
+COPY --from=ghcr.io/astral-sh/uv:0.9 /uv /uvx /usr/local/bin/
+ENV NPM_CONFIG_PREFIX=/opt/codeman-cli
+ENV PATH=$PATH:/opt/codeman-cli/bin
+# CLIs installed at runtime (Settings -> CLIs, npm redirected to ~/.local by installEnv()) live on the
+# persistent home mount, so they survive a container recreate. Appended for the same reason as above.
+ENV PATH=$PATH:/home/${CODEMAN_RUNTIME_USER}/.local/bin
+# pnpm is not an agent CLI: it is here because `dsh plugin` (DeepSeek Harness, which
+# this image leaves to be installed at runtime, see SERVER_INTENTIONAL_OMISSIONS in
+# test/docker-agent-image-coverage.test.ts) spawns a literal `pnpm` with no npm
+# fallback, so the Run menu's "DeepSeek - add a terminal profile" button failed
+# with `dsh: pnpm not found on PATH` (exit 127) on this image. The agent image
+# already carries it for the same reason (#352). It lives in the same
+# runtime-writable prefix as the CLIs, so a session can update it in place.
+RUN npm install --global \
+      @anthropic-ai/claude-code@2.1.258 \
+      @google/gemini-cli@0.58.0 \
+      @openai/codex@0.152.1 \
+      opencode-ai@1.18.26 \
+      pnpm@12.6.0 \
+ && npm cache clean --force
+
+# Keep the web server and every local Codeman session unprivileged. PUID and
+# PGID match the host-owned application-data directory mounted by Compose. The
+# requested GID may not exist in the base image, and a host UID such as 1000 may
+# already belong to the baked `node` account, so handle both cases explicitly.
+#
+# The trailing chown hands the CLI prefix (/opt/codeman-cli, populated above)
+# to that same account, so a session can self-update one of the CLIs in place.
+# /usr/local stays root-owned throughout — see the comment on the npm install
+# above for why that boundary matters.
+RUN set -eux; \
+    case "${PUID}" in ''|*[!0-9]*) echo "PUID must be numeric" >&2; exit 1;; esac; \
+    case "${PGID}" in ''|*[!0-9]*) echo "PGID must be numeric" >&2; exit 1;; esac; \
+    if [ "${PUID}" -eq 0 ]; then \
+      echo "PUID must identify an unprivileged account, not root" >&2; \
+      exit 1; \
+    fi; \
+    if ! getent group "${PGID}" >/dev/null; then \
+      groupadd --gid "${PGID}" codeman-runtime; \
+    fi; \
+    existing_user="$(getent passwd "${PUID}" | cut -d: -f1 || true)"; \
+    if [ -n "${existing_user}" ]; then \
+      usermod \
+        --login "${CODEMAN_RUNTIME_USER}" \
+        --gid "${PGID}" \
+        --home "/home/${CODEMAN_RUNTIME_USER}" \
+        --move-home \
+        --shell /bin/bash \
+        "${existing_user}"; \
+    else \
+      useradd \
+        --uid "${PUID}" \
+        --gid "${PGID}" \
+        --create-home \
+        --home-dir "/home/${CODEMAN_RUNTIME_USER}" \
+        --shell /bin/bash \
+        "${CODEMAN_RUNTIME_USER}"; \
+    fi; \
+    chown -R "${PUID}:${PGID}" /opt/codeman-cli /opt/codeman-az-extensions
+
+WORKDIR /opt/codeman
+
+COPY --from=build /opt/codeman /opt/codeman
+
+# CODEMAN_IN_CONTAINER tells the self-updater it must restart by exiting rather
+# than by asking an init system that is not here (src/web/self-update.ts).
+# NODE_ENV stays `production`; the updater passes `npm install --include=dev`
+# explicitly, since that value would otherwise omit the build toolchain.
+ENV CODEMAN_IN_CONTAINER=1 \
+    CODEMAN_PORT=3000 \
+    HOME=/home/${CODEMAN_RUNTIME_USER} \
+    NODE_ENV=production
+
+# Runtime defaults for the entrypoint, matching the account created above.
+ENV PGID=${PGID} PUID=${PUID}
+
+EXPOSE 3000
+
+# The container starts as root so the entrypoint can correct the ownership of
+# the host bind mounts, which the daemon creates as root whenever they do not
+# already exist. The entrypoint then drops to PUID:PGID with setpriv, so the
+# server itself never runs privileged. Setting `user:` in Compose bypasses both
+# steps, leaving the caller in full control.
+COPY docker/entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod 0755 /usr/local/bin/entrypoint.sh
+
+# Declare the optional identity immediately before configuring it so a change
+# invalidates only this final layer. This is declarative setup: a persisted
+# ~/.gitconfig in CODEMAN_APPDATA_PATH still overrides the system-level values.
+ARG GIT_USER_EMAIL=
+ARG GIT_USER_NAME=
+RUN set -eux; \
+    if [ -n "${GIT_USER_NAME}" ] || [ -n "${GIT_USER_EMAIL}" ]; then \
+      if [ -z "${GIT_USER_NAME}" ] || [ -z "${GIT_USER_EMAIL}" ]; then \
+        echo 'Git user name and email must both be set when configuring Git identity' >&2; \
+        exit 1; \
+      fi; \
+      git config --system user.name "${GIT_USER_NAME}"; \
+      git config --system user.email "${GIT_USER_EMAIL}"; \
+    fi
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
+
+CMD ["node", "dist/index.js", "web"]

docs/agent-control-plan.md

@@ -0,0 +1,769 @@
+# Agent Control Plan: skill packaging + wait primitives
+
+**Status**: steps 1 to 8 DONE and RELEASED. The wait primitives and the skill itself
+(steps 1 to 5) shipped in **1.13.0**; the `codeman skill install` CLI, per-case injection
+and `agentSkillEnabled` (step 6) shipped in **1.14.1** and were republished with fixes in
+**1.14.2**. Steps 1 to 5 were multi-round verified on 2026-08-08, step 6 on 2026-08-09;
+see [§7 Build log](#7-build-log-what-actually-happened) for what shipped, what each
+verification round found, and the two items that genuinely remain open (§2.4's footgun
+guard and the Part 3 deferrals).
+
+**Date**: 2026-08-08
+**Scope**: Part 1 (agent skill) and Part 2 (wait primitives) were specified and built.
+Parts 3 to 5 are captured so they are not lost, but remain deliberately deferred.
+
+---
+
+## 0. Where this came from: what herdr does
+
+[herdr](https://github.com/herdrdev/herdr) (Rust, Apache-2.0, ~25.8k stars) is a terminal
+multiplexer built around AI coding agents. Relevant findings from the research pass:
+
+| Capability      | How herdr does it                                                                                                                                                                                                             |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Agent state     | Four states (`idle`, `working`, `blocked`, `done`) that roll up pane to tab to workspace in a sidebar                                                                                                                         |
+| Detection       | Lifecycle hooks where the agent supports them (it names Pi and MastraCode), otherwise TOML manifests matched against a live bottom-buffer snapshot. Bundled manifests plus remote updates from herdr.dev, local overrides win |
+| Control API     | Newline-delimited JSON over a Unix socket (`~/.config/herdr/sessions/<name>/herdr.sock`), `{"id":"req_1","method":"pane.split","params":{}}`, dot-notation methods, plus long-lived event subscriptions                       |
+| Discoverability | `herdr api schema` prints a machine-readable schema                                                                                                                                                                           |
+| Agent skill     | `npx skills add herdrdev/herdr --skill herdr -g`, a SKILL.md wrapping the CLI, guarded by `test "${HERDR_ENV:-}" = 1` so an agent outside a herdr pane refuses to act                                                         |
+| Persistence     | Background server, detach with `ctrl+b q`, snapshot restore of workspaces/tabs/panes/cwd/layout, experimental screen-history replay, agent resume via native session ids, live PTY handoff across server replacement          |
+| Plugins         | `herdr-plugin.toml` manifest, actions, event hooks, plugin panes, link handlers, GitHub-topic marketplace index                                                                                                               |
+
+The commands the skill teaches the agent:
+
+| Group     | Commands                                                                                                                                                                                                                                                |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| workspace | `workspace list`, `workspace create`                                                                                                                                                                                                                    |
+| tab       | `tab list --workspace <id>`, `tab create`                                                                                                                                                                                                               |
+| pane      | `pane current`, `pane list`, `pane layout`, `pane split --current --direction right --cwd <path> --no-focus`, `pane run <id> "<cmd>"`, `pane wait-output <id> --match/--regex <p> --timeout <ms>`, `pane read <id> --source visible\|recent\|detection` |
+| agent     | `agent list`, `agent start <name> --kind <type> --pane <id>`, `agent prompt <name> "<text>" --wait --timeout <ms>`, `agent wait <name> --until <state> --timeout <ms>`, `agent send-keys`, `agent get`, `agent read`                                    |
+
+### The honest comparison
+
+herdr and Codeman are not the same product. herdr is a local, keyboard-first multiplexer with
+no server, no web UI, and no autonomy layer. Codeman is a server with a browser and mobile UI,
+remote and Docker cases, respawn, Ralph, cron, and the orchestrator, none of which herdr has.
+
+What herdr genuinely does better is being **callable by the agent running inside it**. For
+Codeman that is a packaging problem plus one missing primitive, not an architecture problem.
+
+---
+
+## 1. Gap analysis
+
+| herdr capability             | Codeman equivalent today                                                                                           | Gap                                                                                   |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| `pane split` + `agent start` | `POST /api/quick-start`, `POST /api/sessions`                                                                      | none, already there                                                                   |
+| `agent prompt`               | `POST /api/sessions/:id/input` with `clientId`+`seq` exactly-once                                                  | no `--wait`                                                                           |
+| `pane read`                  | `GET /api/sessions/:id/output`, `GET /api/sessions/:id/terminal?full=1`                                            | none                                                                                  |
+| `agent list` / `agent get`   | `GET /api/sessions`, `GET /api/sessions/unified`, `GET /api/status`                                                | none                                                                                  |
+| `agent wait --until <state>` | SSE only (`/api/events`)                                                                                           | **missing**, and SSE is impractical from a shell tool                                 |
+| `pane wait-output --match`   | nothing                                                                                                            | **missing**                                                                           |
+| Skill file                   | README section "Driving Codeman from an Agent"                                                                     | **not packaged**, an agent will never find it                                         |
+| Env guard `HERDR_ENV=1`      | `CODEMAN_MUX=1`, `CODEMAN_API_URL`, `CODEMAN_SESSION_ID` already exported at spawn                                 | none, the guard variables exist                                                       |
+| `blocked` state              | hook events (`permission_prompt`, `elicitation_dialog`) plus CSS classes plus the phone overview NEEDS YOU section | not in the wire contract (`SessionStatus = 'idle' \| 'busy' \| 'stopped' \| 'error'`) |
+| `api schema`                 | hand-written `docs/api-reference.md`                                                                               | no machine-readable schema                                                            |
+| Detection manifests          | hardcoded in `usage-limit-patterns.ts`, `respawn-*-patterns`, `regex-patterns.ts`                                  | patterns are code, not data                                                           |
+| Plugin runtime               | deliberately refused, see `docs/extending-codeman.md`                                                              | not a gap, a decision                                                                 |
+| Session handoff on restart   | tmux owns the PTYs, so they already survive a Codeman restart                                                      | not a gap, solved by architecture                                                     |
+
+**Conclusion**: roughly 90% of the capability surface already exists. Parts 1 and 2 below close
+the two real gaps.
+
+The table is the 2026-08-08 snapshot that motivated the work, kept as written. The three rows
+marked missing are closed since: `GET .../wait` and `GET .../wait-output` shipped in 1.13.0, and
+the skill is packaged at `skills/codeman` (npm tarball included). `blocked` as a wire-contract
+state, and the machine-readable schema, are still open (Parts 3 and 4).
+
+---
+
+## 2. Part 1: the Codeman agent skill
+
+### 2.1 Goal
+
+An agent running inside a Codeman session can discover and correctly drive Codeman without the
+user pasting API docs into the prompt, and without inventing dangerous calls.
+
+### 2.2 Layout and distribution
+
+The `npx skills` CLI (vercel-labs/skills) clones a GitHub repo and looks for
+`skills/<name>/SKILL.md`. Claude Code natively discovers `.claude/skills/<name>/SKILL.md` in a
+project and `~/.claude/skills/` globally. Both are satisfied with one source of truth plus a
+symlink, which is the pattern this repo already uses for `remotion-best-practices`.
+
+```
+skills/
+  codeman/
+    SKILL.md            <- single source of truth
+    reference/
+      endpoints.md      <- full endpoint tables, loaded on demand
+      recipes.md        <- worked multi-session orchestration examples
+.claude/skills/codeman -> ../../skills/codeman     (symlink, dogfooding in this repo)
+```
+
+Adding a `skills/` directory to the repo root costs one entry in the GitHub listing. CLAUDE.md
+keeps the root short on purpose, so this needs a conscious sign-off; the alternative is
+`docs/skills/codeman/` with a `--skill` path argument, which breaks the one-liner install.
+**Recommendation**: accept `skills/` at the root, because the install one-liner is the whole
+point of shipping a skill.
+
+Install paths, in order of how a user gets it:
+
+1. `npx skills add Ark0N/Codeman --skill codeman -g` (global, any agent, matches the herdr flow).
+2. `codeman skill install [--global | --case <name>]`, a new CLI subcommand writing the same
+   file. This is the path for users who installed via npm and never cloned the repo.
+3. **Automatic per-case injection**, modeled exactly on `applyStatusLineConfig(casePath, enabled)`
+   in `hooks-config.ts`: write `<case>/.claude/skills/codeman/SKILL.md` at case creation,
+   gated on a new setting. Codeman already writes `<case>/.claude/settings.local.json` hooks
+   through `writeHooksConfig()`, so this is the same mechanism with the same lifecycle.
+
+Setting name: `agentSkillEnabled`. Synced (not per-device), since it changes on-disk case
+content rather than display. Default: **ON after the dogfooding phase, OFF in the first
+release**. Rationale for starting OFF: Claude Code loads every skill's name and description
+into context on every turn, so an always-on skill has a small permanent token cost, and we
+should measure that we are buying something with it first.
+
+### 2.3 SKILL.md content
+
+Frontmatter, per the skills convention (`name` + `description` required):
+
+```yaml
+---
+name: codeman
+description: >-
+  Control Codeman, the session manager this agent is running inside: list sessions,
+  start worker sessions, send prompts, read terminal output, and wait for other agents
+  to finish. Only usable when CODEMAN_MUX=1.
+---
+```
+
+Body sections, in order:
+
+**1. Guard (first thing, non-negotiable).**
+
+```bash
+test "${CODEMAN_MUX:-}" = 1 || { echo "not inside a Codeman session"; exit 1; }
+API="${CODEMAN_API_URL:?CODEMAN_API_URL not set, refusing to guess}"
+SELF="${CODEMAN_SESSION_ID:-}"
+```
+
+If `CODEMAN_MUX` is not `1`, the agent must stop and say it is not running inside a
+Codeman-managed session. Same shape as herdr's `HERDR_ENV` guard, and the variables are
+already exported by `tmux-manager.buildEnvExports()`. No fallback URL when
+`CODEMAN_API_URL` is unset: any guess is the wrong scheme on an HTTPS install (prod is
+HTTPS with a self-signed cert, hence `curl -sk` throughout), and a server the agent
+cannot identify is not one it should be driving.
+
+**2. Rules of the road.** Lifted and tightened from README lines 666 to 745:
+
+- Single-line input only. Multi-line breaks the agent TUI (Ink).
+- Always send `clientId` + a monotonic `seq` on `POST .../input` so a retry cannot double-deliver.
+- Envelope is `{success, data}`; a few legacy GETs are bare, so read `body.data ?? body`.
+- Add `-u admin:"$CODEMAN_PASSWORD"` when a password is set. Prod is HTTPS, so `curl -sk`.
+- Prefer `/api/v1/*`, the stable alias.
+
+**3. Safety rules (the section that does not exist anywhere today).**
+
+- Never act on `$CODEMAN_SESSION_ID`. That is you.
+- Only `DELETE` sessions **you created in this conversation**, by exact id. Keep the list.
+- Never bulk-delete, never loop a `DELETE` over `/api/sessions`. There is no undo.
+- Never `tmux kill-session`, `pkill tmux`, `pkill claude`. Use the API.
+- Creating a session consumes a slot against the 50-session cap. Clean up what you start.
+
+**4. Recipes**, each one a single copy-pasteable curl:
+
+| Task                 | Call                                                                                                                                                                    |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| list sessions        | `GET /api/v1/sessions`                                                                                                                                                  |
+| find yourself        | match ids by PREFIX of `$CODEMAN_SESSION_ID` (Docker cases truncate it to 8 chars, so an equality check never fires there)                                              |
+| start a worker       | `POST /api/v1/quick-start {caseName, mode, effort}`                                                                                                                     |
+| send a prompt        | `POST /api/v1/sessions/:id/input {input:"…\r", useMux:true, clientId, seq}` (the trailing `\r` is what sends Enter; without it the text sits on the prompt unsubmitted) |
+| send prompt and wait | `POST /api/v1/sessions/:id/input {input:"…\r", wait:"stop", waitTimeout:600000}` (Part 2)                                                                               |
+| wait for a worker    | `GET /api/v1/sessions/:id/wait?until=stop,blocked&timeout=300000` (Part 2)                                                                                              |
+| wait for a marker    | `GET /api/v1/sessions/:id/wait-output?match=DONE_<random>&timeout=120000` (Part 2; unique per call, per §3.3's repaint rule)                                            |
+| read output          | `GET /api/v1/sessions/:id/output`                                                                                                                                       |
+| read full scrollback | `GET /api/v1/sessions/:id/terminal?full=1`                                                                                                                              |
+| watch sub-agents     | `GET /api/v1/subagents`                                                                                                                                                 |
+| schedule work        | `POST /api/v1/cron/jobs`                                                                                                                                                |
+| clean up             | `DELETE /api/v1/sessions/:id`                                                                                                                                           |
+
+**5. Pointer to `reference/endpoints.md`** for anything not in the table, so the always-loaded
+part of the skill stays small.
+
+### 2.4 An ergonomics guard worth adding server-side
+
+The skill will tell the agent not to act on itself, but a confused agent can still try. Propose:
+the skill sends `X-Codeman-Caller-Session: $CODEMAN_SESSION_ID` on every request, and the server
+refuses destructive operations (`DELETE /api/sessions/:id`, kill, respawn stop) when that header
+equals the target id, with a clear error.
+
+This is a **footgun guard, not a security control**: any caller can omit the header. Document it
+as such so nobody mistakes it for a boundary. It costs about 10 lines in `route-helpers.ts`.
+
+### 2.5 Verification
+
+Per the always-end-to-end-test rule, "the skill exists" is not done. Done is:
+
+1. Symlink it into `.claude/skills/`, start a real throwaway Codeman session, and ask that agent
+   to "start a worker session that runs the test suite and tell me when it finishes".
+2. Confirm from the outside that exactly one new session appeared, got the prompt, and that the
+   lead agent waited rather than polling in a busy loop.
+3. Confirm the guard: run the same prompt in a shell with `CODEMAN_MUX` unset and confirm refusal.
+4. Confirm cleanup: the worker session is deleted by exact id and no other session was touched.
+
+Never run this against `w1`/`w2`/`w3`.
+
+### 2.6 Files touched
+
+- `skills/codeman/SKILL.md` (new), `skills/codeman/reference/*.md` (new)
+- `.claude/skills/codeman` symlink (new)
+- `src/cli.ts` (new `skill install` subcommand)
+- `src/hooks-config.ts` (new `applyAgentSkill(casePath, enabled)`, mirroring `applyStatusLineConfig`)
+- `src/web/schemas.ts` (`agentSkillEnabled` in `SettingsUpdateSchema`, which is `.strict()`)
+- `src/web/routes/system-routes.ts` (settings PUT must resolve the flag from `merged`, never
+  from the raw body, per the partial-PUT invariant)
+- `src/web/public/settings-ui.js` + `index.html` (checkbox)
+- `package.json` `files` array, so `skills/` ships to npm
+- README pointer, `docs/extending-codeman.md` seam 3 pointer
+
+---
+
+## 3. Part 2: wait primitives
+
+### 3.1 Goal
+
+Make Codeman orchestratable from a shell tool. Today the only "tell me when" channel is SSE,
+which a curl-driven agent cannot practically consume: it would have to hold a streaming
+connection and parse events inline. herdr solves this with blocking CLI calls. Codeman should
+solve it with bounded long-poll endpoints.
+
+All three additions are **additive**, so the versioning policy stays intact (new endpoints and
+new optional fields are non-breaking).
+
+### 3.2 The signal model
+
+A waiter resolves on the first of a set of signals. Sources that already exist:
+
+| Signal    | Source today                                                                                                                                  |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `idle`    | `Session` emits `idle` (session.ts ~1775 for Claude, ~2101 for shell), wired at `session-listener-wiring.ts:402`                              |
+| `working` | `Session` emits `working` (session.ts ~1788), wired at `session-listener-wiring.ts:401`                                                       |
+| `stop`    | `POST /api/hook-event` with `event: 'stop'`, the definitive "Claude finished responding" signal already used by `controller.signalStopHook()` |
+| `blocked` | `POST /api/hook-event` with `permission_prompt` or `elicitation_dialog`                                                                       |
+| `exit`    | `Session` emits `exit`                                                                                                                        |
+
+`stop` is the highest-quality signal for "the turn is over" and should be the documented default
+for orchestration. `idle` is heuristic: output stabilization plus prompt detection, and it can
+flap mid-turn when a spinner pauses. External CLI modes (`isExternalCliMode()`) have no stop
+hook at all, so for opencode/codex/gemini/antigravity only `idle`, `working` and `exit` are
+available. **The skill and the docs must say which signals exist per mode**, otherwise an agent
+waits forever on `stop` in a codex session.
+
+### 3.3 Endpoint specs
+
+#### A. `GET /api/sessions/:id/wait`
+
+| Param     | Type                                           | Default          | Notes                                                        |
+| --------- | ---------------------------------------------- | ---------------- | ------------------------------------------------------------ |
+| `until`   | comma list of `idle,working,stop,blocked,exit` | `stop,idle,exit` | resolves on first match                                      |
+| `timeout` | ms                                             | 60000            | clamped to `MAX_WAIT_MS` (600000)                            |
+| `fresh`   | `0`/`1`                                        | `0`              | `1` requires a _transition_, ignoring the state at call time |
+
+Response (always 200 unless the session is missing or a cap is hit):
+
+```json
+{
+  "success": true,
+  "data": {
+    "signal": "stop",
+    "timedOut": false,
+    "immediate": false,
+    "ended": false,
+    "waitedMs": 8421,
+    "status": "idle",
+    "sessionId": "...",
+    "until": ["stop", "idle", "exit"],
+    "limitPaused": false
+  }
+}
+```
+
+`until` is echoed back because the server may narrow it: `stop`/`blocked` are dropped
+from the DEFAULT set for external CLI modes (asking for them EXPLICITLY is a 400
+instead, since omitting `until` must never 400). `limitPaused` tells a caller that a
+timeout was expected rather than a stall worth retrying hard.
+
+**A timeout is not an error.** `{"timedOut": true, "signal": null}` with HTTP 200, so a caller
+can loop without treating every poll boundary as a failure. Errors are reserved for
+`NOT_FOUND` (unknown or not-owned session) and `SESSION_BUSY` (waiter cap exceeded).
+
+`immediate: true` means the session was already in the requested state and `fresh` was not set.
+
+#### B. `GET /api/sessions/:id/wait-output`
+
+| Param     | Type                           | Default  | Notes                                                     |
+| --------- | ------------------------------ | -------- | --------------------------------------------------------- |
+| `match`   | literal string, 1 to 200 chars | required | substring match against ANSI-stripped output              |
+| `nocase`  | `0`/`1`                        | `0`      | case-insensitive compare                                  |
+| `from`    | `now` \| `buffer`              | `now`    | `buffer` scans the existing text buffer first, then waits |
+| `timeout` | ms                             | 60000    | clamped to `MAX_WAIT_MS`                                  |
+
+Response: `{ matched: true, timedOut: false, snippet: "...", waitedMs }`.
+
+**No regex in v1, deliberately.** `search-service.ts` already avoids regex specifically so there
+is no ReDoS surface, and this endpoint would be even more exposed since the pattern is attacker
+supplied and the input is a live stream. herdr can offer `--regex` because Rust's regex crate is
+linear-time with no backtracking; JS `RegExp` is not. If regex is wanted later, the honest
+options are a length-capped subset compiled once with a match budget, or `re2`. Note it and move on.
+
+Implementation detail that will bite if missed: a match can straddle two PTY chunks. Keep a
+carry buffer of `match.length - 1` bytes from the previous chunk and test `carry + chunk`.
+
+⚠️ **`from=now` does not mean "printed after you asked".** tmux repaints the visible
+screen on attach, resize, or any TUI redraw, and a repaint arrives as ordinary `terminal`
+data. Observed live: a marker echoed a minute earlier matched instantly on a fresh
+`from=now` wait. This is inherent to a terminal multiplexer, not fixable in the registry,
+so the contract is: **use a marker unique per call** (`echo DONE_$RANDOM`), never a
+generic one like `BUILD OK`. The skill's recipes must show that.
+
+The returned snippet is whitespace-collapsed (blank runs to a single newline) for
+readability only; matching runs on the raw stripped text. Without it, a real pane's
+`\r\n` padding between the prompt and the match fills the whole context window with
+nothing, which was the first thing the live test showed.
+
+#### C. `wait` on the existing input endpoint
+
+`POST /api/sessions/:id/input` gains two optional fields:
+
+```json
+{ "input": "run the tests\r", "useMux": true, "clientId": "agent-1", "seq": 7, "wait": "stop", "waitTimeout": 600000 }
+```
+
+(The trailing `\r` is required on every input body: `sendInput` sends Enter only
+when the input contains a carriage return.)
+
+Response gains `"wait": { "signal": "stop", "timedOut": false, "waitedMs": 41230 }`.
+
+This is the important one, because it closes a race the standalone `GET .../wait` cannot: between
+"input delivered" and "session flips to working" there is a window where a naive
+send-then-wait sees the _pre-existing_ idle state and returns instantly. The combined endpoint
+**registers the waiter before writing**, so that window does not exist. This is exactly why herdr
+ships `agent prompt --wait` as its own thing.
+
+`wait` accepts `true` (the default signal set) or the same comma grammar as `until`.
+Both new fields are `.nullish()`, not `.optional()`: a third-party caller building the
+body with `JSON.stringify` keeps an explicit `null` on the wire, and `.optional()`
+rejects that with `INVALID_INPUT`. That gotcha has shipped as a real bug twice.
+
+Two behaviors to preserve carefully:
+
+- **`useMux` is fire-and-forget today.** The handler responds without awaiting `writeViaMux`, on
+  purpose (a tmux child process must not block the HTTP response). With `wait` present the
+  handler already has to stay open, so it can await delivery, and a `writeViaMux` failure becomes
+  observable for the first time. The non-wait path must keep its current fire-and-forget shape
+  byte for byte.
+- **Duplicate suppression.** A tagged redelivery (`clientId`+`seq` already applied) returns 200
+  without writing. With `wait` set it still waits, since the caller's intent is "tell me when
+  this settles". But it waits with `requireTransition: false`, unlike a fresh delivery: the
+  original turn may be long over, and requiring a new transition would block a redelivery until
+  timeout for no reason. Fresh delivery requires a transition, a duplicate answers from the
+  current state.
+- **Capacity rollback.** `shouldApplyInput()` MUTATES (it records the seq), and it runs before
+  the waiter is registered. If registration then fails on a full pool, the handler must call
+  `forgetInputSeq` before returning `SESSION_BUSY`, or the caller's retry is rejected as a
+  duplicate and the input is lost by the very mechanism reliable delivery exists for.
+
+### 3.4 Module design
+
+New file `src/web/session-wait-registry.ts`, with the IO-free core unit-testable in isolation
+(same split as `self-update.ts`):
+
+```ts
+type WaitSignal = 'idle' | 'working' | 'stop' | 'blocked' | 'exit';
+
+waitForSignal(sessionId, { until: Set<WaitSignal>, timeoutMs, requireTransition }): Promise<WaitResult>
+notifySignal(sessionId, signal: WaitSignal): void
+waitForOutput(sessionId, { match, nocase, timeoutMs }): Promise<OutputWaitResult>
+notifyOutput(sessionId, chunk: string): void
+cancelAll(sessionId, reason): void
+```
+
+Wiring points, all existing:
+
+- `src/web/session-listener-wiring.ts` around lines 190 and 200 already handles `working` and
+  `idle` and broadcasts them. Add a `notifySignal()` call next to each broadcast, plus `exit`.
+- `src/web/routes/hook-event-routes.ts` already switches on `event` for the respawn controller.
+  Add `notifySignal(sessionId, 'stop' | 'blocked')` in the same switch.
+- Output: `notifyOutput()` rides the ALREADY-attached `terminal` listener in
+  session-listener-wiring.ts. An earlier draft had the registry hand out attach/detach
+  callbacks so a listener could be added lazily; that was deleted once it was clear no
+  second listener is needed at all. The cost is one Map lookup per PTY chunk, which is why
+  the no-waiter check comes before the ANSI strip.
+- Session deletion calls `notifySignal('exit')` then `cancelAll()`, so no promise is left
+  hanging. Both are required: `_doCleanupSession` detaches the session's listeners BEFORE
+  `session.stop()`, so on a delete the PTY exit event never reaches the registry, and an
+  `until=exit` caller would otherwise get a bare `ended` instead of its signal. Found by
+  live-testing the delete path, not by the unit tests.
+
+Memory-leak discipline, per the 24-hour-session rules: every waiter owns a timer that is cleared
+on resolve, the per-session waiter set is deleted when it empties, and the output listener is
+removed with it. `test/memory-leak-prevention.test.ts` should grow a case for this.
+
+Caps in a new `src/config/agent-wait.ts` (limits live in `src/config/`, env-overridable):
+
+| Constant                  | Default | Why                                     |
+| ------------------------- | ------- | --------------------------------------- |
+| `MAX_WAIT_MS`             | 600000  | an unbounded long-poll is a socket leak |
+| `DEFAULT_WAIT_MS`         | 60000   | short enough to survive most proxies    |
+| `MAX_WAITERS_PER_SESSION` | 16      |                                         |
+| `MAX_WAITERS_TOTAL`       | 128     | same reasoning as `MAX_SSE_CLIENTS`     |
+
+Exceeding a cap returns `SESSION_BUSY`, not a silent queue.
+
+### 3.5 Transport concerns
+
+Fastify is constructed with defaults in `server.ts:329-331`. `requestTimeout` defaults to 0
+(disabled) and `keepAliveTimeout` (72s) applies between requests, not to an in-flight one, so a
+10-minute in-process hold is fine. **Verify this on the real instance before relying on it.**
+
+Intermediaries are the actual risk. Prod is reached through `tailscale serve`, and users also run
+cloudflared tunnels; both can cut an idle connection. That is why `DEFAULT_WAIT_MS` is 60s and
+why the documented pattern is a client-side loop over short waits rather than one 10-minute call.
+The skill's recipes must show the loop.
+
+### 3.6 Edge cases to get right
+
+| Case                            | Behavior                                                                                                                                                                                                    |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Session already idle, `fresh=0` | return immediately, `immediate: true`                                                                                                                                                                       |
+| Session already idle, `fresh=1` | wait for the next transition into a requested state                                                                                                                                                         |
+| Session dies mid-wait           | resolve with `signal: "exit"` if `exit` was requested, otherwise resolve `timedOut:false, signal:null, ended:true`. Never hang                                                                              |
+| Session deleted mid-wait        | same, resolve, do not throw. Verified live: `until=exit` gets `signal:"exit"`, a concurrent `until=blocked` gets `ended:true`, both in ~0ms                                                                 |
+| Shutdown with a wait pending    | `cancelEverything()` in `stop()`. Verified live: SIGTERM with a 300s wait in flight exits in 1s                                                                                                             |
+| External CLI mode               | `stop` and `blocked` never fire. Reject `until=stop` for those modes with a clear `INVALID_INPUT` rather than hanging until timeout                                                                         |
+| Multi-user                      | goes through `findSessionOrFail(ctx, id, req)`, which already enforces ownership                                                                                                                            |
+| Remote / Docker cases           | signals originate from the same `Session` object, so no special casing. Docker hooks need `CODEMAN_DOCKER_BRIDGE_HOOKS=1` for `stop`/`blocked` to arrive at all; without it, only `idle` works. Document it |
+| Respawn `/clear` mid-wait       | a respawn cycle emits `idle`. Callers waiting on `stop` are unaffected; callers on `idle` may resolve early. Documented, not fixed                                                                          |
+| Limit pause                     | if the session is paused on a usage limit, nothing will fire until the reset. The wait times out honestly. Consider surfacing `limitPaused: true` in the response so the caller can back off                |
+
+### 3.7 Tests
+
+- `test/session-wait-registry.test.ts` (pure): immediate resolve, transition-required, multi-signal
+  first-wins, timeout, cap exceeded, cancel on session end, no listener leak after resolve,
+  chunk-straddling output match, case-insensitive match.
+- `test/routes/session-wait-routes.test.ts` (`app.inject()`, no port): all three endpoints against
+  a `MockSession`, including the 200-with-`timedOut` contract and the ownership 404.
+- `test/routes/session-input-wait.test.ts`: the send-and-wait race, plus proof that the non-wait
+  path is unchanged (still returns before `writeViaMux` settles).
+- Live verification on a throwaway session before COM, per the always-end-to-end-test rule.
+
+### 3.8 Files touched
+
+- `src/config/agent-wait.ts` (new)
+- `src/web/session-wait-registry.ts` (new)
+- `src/web/session-listener-wiring.ts` (notify on idle/working/exit)
+- `src/web/routes/hook-event-routes.ts` (notify on stop/blocked)
+- `src/web/routes/session-routes.ts` (two new routes, `wait` fields on input)
+- `src/web/schemas.ts` (`SessionWaitQuerySchema`, `SessionWaitOutputQuerySchema`, extend
+  `SessionInputWithLimitSchema`. Note: `.optional()` rejects `null`, so the frontend and any
+  generated client must send `undefined`, never `null`)
+- `docs/api-reference.md`, `docs/extending-codeman.md`, README API table
+- `skills/codeman/SKILL.md` recipes (Part 1 depends on this)
+
+---
+
+## 4. Deferred: parts 3 to 5
+
+Not in scope now, kept here so they are not lost.
+
+### Part 3: promote `blocked` to a first-class state
+
+`SessionStatus` is `'idle' | 'busy' | 'stopped' | 'error'`. "Needs you" exists three times over:
+hook events, the `tab-alert-action` CSS class, and the phone overview NEEDS YOU section, each
+re-deriving it. herdr makes `blocked` a real state that rolls up.
+
+Add `blocked` (and possibly `done`) to `SessionStatus`, set it from the same hook events that
+Part 2 uses as wait signals, and clear it on the next `working`/`stop`. Then the tab strip, the
+mobile overview, the wait endpoints, and any external agent read one field.
+
+Cost: `SessionStatus` is a widely-consumed union, so every exhaustive `switch` (the codebase has
+`assertNever` and `noFallthroughCasesInSwitch`) will need a branch. That is a feature, it makes
+the compiler find every site. This is a **minor** bump, not a patch: it widens a public type in
+the HTTP contract.
+
+### Part 4: `GET /api/schema`
+
+herdr ships `herdr api schema`. Every Codeman route is already Zod-validated, so
+`zod-to-json-schema` over `schemas.ts` gives a self-describing API almost free. Value: third-party
+tools and the skill stop drifting from hand-written docs. Open question: whether to emit full
+OpenAPI (`@fastify/swagger` would need per-route schema registration, which is a much larger
+change) or just dump the Zod schemas keyed by name (cheap, 80% of the value).
+
+### Part 5: detection manifests instead of hardcoded patterns
+
+CLI-specific readiness, blocked and usage-limit patterns live in code across
+`usage-limit-patterns.ts`, the respawn pattern helpers and `regex-patterns.ts`. Externalizing the
+per-CLI ones into data files would make adding a sixth CLI a data change instead of a code change.
+
+**Do not copy the remote-update part.** herdr auto-fetches manifest updates from herdr.dev.
+Codeman auto-pulling behavioral rules from a vendor server contradicts its security posture.
+Bundled manifests plus local override only, no network.
+
+### Explicit non-goals
+
+- **Plugin runtime and marketplace.** `docs/extending-codeman.md` already argues this: a plugin
+  runtime means third-party code inside a process that spawns agents with your credentials, on a
+  server people expose over a tunnel. The reasoning still holds. If the marketplace _pattern_ is
+  wanted, apply it to data (web tabs, case templates, cron recipes), never to executable code.
+- **Live PTY handoff on restart.** herdr needs it because it owns the terminals. Codeman
+  delegates to tmux, so PTYs already survive a self-update restart.
+- **Socket API.** HTTP plus SSE is the existing, documented, stable contract. A second transport
+  would double the surface for no capability gain.
+
+---
+
+## 5. Sequencing
+
+| Step | Work                                                                            | Gate                                                                                                                                                                                                                                                                                                                                         |
+| ---- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1 ✅ | `src/config/agent-wait.ts` + `session-wait-registry.ts` + unit tests            | 48 tests green                                                                                                                                                                                                                                                                                                                               |
+| 2 ✅ | `GET .../wait` + wiring in listener-wiring, hook-event-routes, server teardown  | 15 route tests green; live-verified on an isolated `CODEMAN_INSTANCE=waittest` instance (immediate resolve, 400 on a bad signal, 200+`timedOut` on timeout, hook `stop` and `permission_prompt`→`blocked` waking an in-flight wait, delete delivering `exit`, SIGTERM not blocked); full `test:ci` sweep green                               |
+| 3 ✅ | `GET .../wait-output`                                                           | 16 route tests green; live-verified on real PTY bytes (`echo MARKER` waking a blocked request in ~1s, `from=buffer` immediate hit, never-seen marker timing out at exactly 2001ms, nocase, `regex` refused with a 400); full `test:ci` sweep green                                                                                           |
+| 4 ✅ | `wait` field on `POST .../input`, non-wait path proven unchanged                | 16 route tests green; live-verified (no-wait returns in 26ms with the historical bare body; an idle session did NOT satisfy a `wait` request, blocking the full 2001ms, which is the race the endpoint exists to close; the stop hook resolved a send-and-wait at 1510ms and the input was confirmed in the tmux pane; `wait:null` accepted) |
+| 5 ✅ | `skills/codeman/SKILL.md` + reference files + `.claude/skills` symlink          | live dogfood: a real session orchestrates a worker end to end                                                                                                                                                                                                                                                                                |
+| 6 ✅ | `codeman skill install` CLI + `applyAgentSkill()` + `agentSkillEnabled` setting | 10 unit tests (`test/agent-skill.test.ts`) + real-server case-creation tests (`test/quick-start.test.ts`, incl. the settings PUT accepting the key) green; CLI verified live (install/uninstall, global + `--case`, foreign/symlink refusals)                                                                                                 |
+| 7 ✅ | Docs: api-reference, extending-codeman, README                                  | plus `architecture-invariants.md` (§agent-wait-primitives), `CLAUDE.md` and the API reference's per-mode signal table                                                                                                                                                                                                                        |
+| 8 ✅ | COM (minor bump: new endpoints, new setting, new optional fields)               | released as 1.13.0 (wait primitives + skill); step 6 followed in 1.14.1 and was republished as 1.14.2 after live-testing the packaged skill                                                                                                                                                                                                  |
+
+Parts 1 and 2 are independent enough to land separately, but the skill is much less useful
+without the wait endpoints, so the wait work goes first.
+
+## 6. Open questions for the owner
+
+1. ✅ `skills/` at the repo root: accepted (built that way; the install one-liner depends on it).
+2. ✅ `agentSkillEnabled` default: **OFF** for the first release, per §2.2's rationale (skills
+   cost context on every turn; measure before defaulting on). Flip later if dogfooding earns it.
+3. ✅ Both: global install via `npx skills add` / `codeman skill install`, AND per-case
+   auto-injection behind the (default-off) setting. Injection is add-only at session create and
+   marker-guarded, so a user-authored copy is never touched.
+4. Is `X-Codeman-Caller-Session` self-protection worth the 10 lines, given it is a footgun guard
+   and not a security boundary? (Still open, not built with step 6.)
+5. ✅ Regex support in `wait-output`: literal-only shipped, and a `regex` query param is
+   rejected with a 400 rather than ignored, so an agent that assumed otherwise cannot
+   silently wait on the wrong thing.
+
+---
+
+## 7. Build log: what actually happened
+
+Written at the end of the build so the next person inherits the reasoning, not just the
+diff. Process artifacts (per-agent briefs, findings, reports) live in the gitignored
+`tmp/agent-wait-review/`; this section is the part worth keeping.
+
+### What shipped
+
+| Piece                                                                           | Files                                                                                                                              |
+| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Bounds + clamping                                                               | `src/config/agent-wait.ts` (new)                                                                                                   |
+| Blocking-wait registry                                                          | `src/web/session-wait-registry.ts` (new, IO-free, unit-tested)                                                                     |
+| `GET .../wait`, `GET .../wait-output`, `wait`/`waitTimeout` on `POST .../input` | `src/web/routes/session-routes.ts`                                                                                                 |
+| Signal wiring                                                                   | `session-listener-wiring.ts` (idle/working/exit + output), `hook-event-routes.ts` (stop/blocked), `server.ts` (teardown, shutdown) |
+| Agent skill                                                                     | `skills/codeman/SKILL.md` + `reference/`, `.claude/skills/codeman` symlink, `package.json` `files`                                 |
+| Docs                                                                            | `api-reference.md`, `extending-codeman.md`, `architecture-invariants.md`, `README.md`, `CLAUDE.md`                                 |
+| Tests                                                                           | `test/session-wait-registry.test.ts`, three `test/routes/session-*wait*.test.ts`, `http-contract.test.ts`, `mock-session.ts`       |
+
+### Bugs found in ADJACENT code, not in the new feature
+
+These are the highest-value output of the exercise and none were on the plan:
+
+1. **Every Codeman hook was dead on HTTPS installs.** `hooks-config.ts` built the hook
+   curl as `curl -s` with no `-k` while the statusline exporter 300 lines below used
+   `curl -sk` and documented why. Proven with the real hook command: `curl exit=60`
+   without the flag, success with it, and the failure swallowed by the hook's own
+   `2>/dev/null || true`. This silently killed `stop`, `permission_prompt`,
+   `elicitation_dialog`, `idle_prompt`, `teammate_idle` and `task_completed`, taking
+   respawn's definitive idle signals with them. Fixed, **plus** a staleness detector in
+   `refreshStaleCodemanHooks` that regenerates the on-disk config of already-created
+   cases (23 of 26 local cases carried the broken form; fixing the generator alone would
+   have left every one of them broken).
+2. **`buildEnvExports()` exported a wrong-scheme `CODEMAN_API_URL`** (`http://` fallback
+   on an HTTPS install). Now omitted rather than guessed, so in-session guards fail closed.
+3. **Programmatic input is only submitted when it contains `\r`.** `sendInput` sends Enter
+   only if the payload has a carriage return; without it the text sits in the composer
+   forever. Bit this build repeatedly before it was diagnosed, and had leaked into the
+   docs' own examples.
+
+### Design decisions worth not re-litigating
+
+- **A timeout is HTTP 200** with `wait.timedOut`, never a 4xx: callers loop over short
+  waits because tunnels cut idle connections, and every poll boundary would otherwise be
+  indistinguishable from failure.
+- **Send-and-wait must be one endpoint.** A separate POST-then-wait races: between the
+  write and the flip to `working`, a wait sees the stale `idle` and reports the PREVIOUS
+  turn as this one. The waiter is registered before the write.
+- **`stop`/`blocked` exist for `claude` mode only.** They come from Claude Code hooks;
+  `shell` installs none either, so keying off `isExternalCliMode()` was wrong.
+- **Literal matching only, never regex.** JS `RegExp` backtracks; herdr can offer
+  `--regex` because Rust's regex crate is linear-time.
+- **Client-hangup abort listens on `reply.raw` guarded by `writableFinished`.** On
+  `req.raw`, `close` fires when the request BODY ends, which on a POST killed every
+  send-and-wait instantly, and no `app.inject()` test can see it (inject never emits
+  `close`).
+- **Liveness cannot come from `session.pid`.** For a tmux session that is the local
+  `tmux attach` client, not the worker: a worker exiting inside its pane leaves
+  `pane_dead=1` with the client alive, so `pid` never goes null. Liveness is probed at
+  the mux layer, cached (~750 ms) and only on blocking waits, never on the input hot path.
+
+### Verification rounds
+
+Six agents across three rounds, each verifying the previous round's work rather than its
+own. Findings that mattered, in order of severity, were: the dead-pane liveness gap; the
+`reply.raw` abort regression; abandoned long-polls leaking waiter slots; a crashed session
+reporting `idle`; `shell` accepting `until=stop`; and a documented recipe that reported
+success without running its task. Two traps recurred often enough to name:
+
+- **Vacuous passes.** `app.inject()` never emits `close`; a latched `cancelEverything()`
+  in `afterEach` silently killed the registry for every later test in a file; three test
+  files sharing one session id against the process-wide registry let one file's leftover
+  waiter fail another's assertion. Any new wait test needs care on all three.
+- **HTTP-only test instances.** Every isolated instance used during the build was plain
+  HTTP, which is exactly why the HTTPS hook bug survived so long. Test the transport the
+  user actually runs.
+
+### Resolved at wrap-up (2026-08-08, conclusion pass)
+
+- **R2-A**: the fire-and-forget-then-gather-sequentially pattern was **removed from
+  the skill** rather than patched. Signals are edge-triggered with no history, so a
+  `stop` that fires before its waiter registers is unobservable afterwards; a
+  `fresh=0` gather was rejected because the only `until` set that current state can
+  satisfy answers `idle` for a prompt that never submitted, resurrecting the exact
+  false-success failure R2-B had just closed. Flow 3b's pattern B now gathers on
+  latched `wait-output` markers (`from=buffer`), the same mechanism that makes the
+  shell flows reliable; the limitation is recorded in
+  `architecture-invariants#agent-wait-primitives` and `endpoints.md`. The durable
+  fix, a latched last-signal-per-turn on the server, stays with deferred Part 3.
+- Docs F7/F8, F4 and the false-`idle` attribution: `api-reference.md`,
+  `extending-codeman.md` and `architecture-invariants.md` rewritten to the post-fix
+  matcher (one normalized stream, chunk-straddling found, snippet as a rendering of
+  the matched window), the real no-PTY answer (`ended:true`, `aborted:false`,
+  `delivered:false`), and the startup-idle mechanism (a session parked on the trust
+  dialog emits no further `idle`; the false success is the startup transition).
+- Orchestrate #12, #5/R2-B, #6, and R2-C..R2-E: fire-and-forget's empty `data`
+  documented; every send-and-wait retry loop now treats `duplicate:true` +
+  `immediate:true` as "no new turn ran" and reads the terminal before believing it;
+  claude fan-out is pattern A (backgrounded send-and-waits) or the marker gather;
+  readiness budgets rebalanced (5 s stage 1, 45 s stage 3) with the virgin-case
+  floor named; the auth fallback now also reads the supervisor definition
+  (`codeman-web.service` / launchd plist) and accepts `export`-prefixed `.env`
+  lines; `pid != null` is documented as startup-only, never liveness.
+- Both public readiness recipes (extending-codeman.md, README) are bypass-first with
+  the trust probe as the bounded fallback; the worked recipe carries `-k` and fails
+  loudly on an empty SID; the hook `-k`/self-heal fix appears in every
+  "hooks go missing" list; the multi-word-TUI claim is "unreliable", not "never".
+
+### Still open
+
+Both release-checklist items that used to sit here are done: `skills/` is tracked and
+ships through `package.json` `files` (published with 1.13.0, republished with 1.14.2),
+and the changeset was consumed, committed and deployed. What is left:
+
+- Deferred with Part 3: the latched last-signal-per-turn. Nice-to-haves from the
+  reviews: N2 (create the death-watcher inside its `try`, still built one line above
+  it in `GET .../wait`) and converting timeout-shaped test detections into fast
+  assertions.
+- §2.4's `X-Codeman-Caller-Session` footgun guard: still not built (open question 4).
+
+### Step 6 (2026-08-09): install command, per-case injection, the setting
+
+Built to the §2.6 file list, mirroring the statusLine mechanism throughout:
+
+| Piece | Where |
+| ----- | ----- |
+| `applyAgentSkill(casePath, enabled)` + `installAgentSkillInto` / `removeAgentSkillFrom` | `src/hooks-config.ts` |
+| `codeman skill install` / `skill uninstall` (`--global` default, `--case <name>`) | `src/cli.ts` |
+| `agentSkillEnabled` (SYNCED, default OFF) | `schemas.ts` (`SettingsUpdateSchema`), `getAgentSkillEnabled()` on `ConfigPort`/`server.ts`, checkbox in `index.html` + `settings-ui.js` |
+| Injection call sites (Claude mode only) | `POST /api/sessions` next to `refreshStaleCodemanHooks`; `POST /api/quick-start` after the case-create/self-heal blocks (local + docker cases; remote skipped, its path lives on another host) |
+| Tests | `test/agent-skill.test.ts` (10 unit), `test/quick-start.test.ts` (real server: default-off, PUT accepts key, injection on create, shell-mode skipped) |
+
+Decisions worth keeping:
+
+- **Ownership marker, prefix-matched.** The injected SKILL.md ends with
+  `<!-- codeman-managed-agent-skill: … -->`; install/refresh/remove all refuse a copy
+  without the marker (a user's own skill) and match on the PREFIX so a wording change
+  cannot disown older injected copies (the `BACKGROUND_WAKE_MARKER_PREFIX` pattern).
+- **Symlink refusal.** This repo's own dogfooding layout
+  (`.claude/skills/codeman -> ../../skills/codeman`) means the injector must `lstat`
+  the skill dir AND its `skills/` parent and bail on a symlink, or enabling the
+  setting in the Codeman repo itself would overwrite the skill source through the link.
+- **ADD-ONLY at session create**, same shared-`.claude` rationale as the statusLine:
+  a create while the setting is off must not yank the skill out from under other live
+  sessions in the repo. The remove path exists (CLI `skill uninstall`, tests); no
+  automatic sweep removes on toggle-off.
+- **Removal is manifest-based, never `rm -rf`**: only files the packaged source would
+  have written are deleted, directories are pruned bottom-up only if they emptied, so
+  a user's extra notes in `reference/` survive an uninstall.
+- **Source resolution**: `join(moduleDir, '..', 'skills', 'codeman')` works from
+  `src/` (tsx), `dist/` (tsc build), and the npm tarball alike, because all three sit
+  one level below the package root and `files` ships `skills/`.
+- **Nothing acts on the setting at PUT time**: injection reads the merged persisted
+  settings at session create (`readSettings`, ~2s cache), so the partial-PUT invariant
+  (`toggleService` reading `merged`) is untouched by construction.
+
+### 2026-08-09 addendum: cross-session messaging folded into the skill
+
+Claude Code 2.1.224+ ships cross-session messaging: `ListAgents`/`SendMessage`
+tools, a per-session Unix inbox socket, and a registry in
+`~/.claude/sessions/<pid>.json`. Codeman's claude workers are ordinary local Claude
+Code sessions, so the skill now routes task delivery and result collection over it
+when available, while the HTTP primitives keep spawn, readiness, synchronization,
+liveness and delete. New `skills/codeman/reference/messaging.md` (ships with zero
+installer changes: `readAgentSkillSource()` enumerates `reference/*.md` from disk),
+Flow 5 in recipes.md, and §4 in SKILL.md.
+
+Verified live (claude-cli 2.1.226, Linux):
+
+- A message to an idle worker starts a turn and that turn fires the normal `stop`
+  hook (8.3 s send-to-stop measured), so the HTTP wait primitives compose with
+  messaging unchanged; delivery to a busy session lands between tool calls.
+- First contact needs the `name [ref]` form; the bare name errors with the exact
+  string to resend. The `uds:` reply address of an inbound message works as a `to`.
+- The `tmux codeman-<id8>` column in `ListAgents` (and the registry's `tmux` field)
+  is the join key to Codeman session ids. The registry's `sessionId` field starts as
+  the Codeman id (we spawn `claude --session-id <id>`) but drifts after `/clear` or
+  resume, so it must never be the join key.
+- The feature is flag-gated beyond the version: two 2.1.226 sessions on one machine,
+  one with an inbox socket and one without. Absence is a fallback case, not an error.
+- Codeman's default `--dangerously-skip-permissions` spawn puts both ends in the
+  bypassing class, which delivers; mixed classes hold behind an approval dialog that
+  expires unattended (upstream default 5 min), which on a headless worker means the
+  message silently dies. The skill's backstop covers it.
+
+Follow-up, landed in the same PR: local claude spawns now pass
+`--name <session name>` so peers carry Codeman session names. The gate is
+`buildNameCliArgs()` (session-cli-builder.ts), fail-closed at
+`CLAUDE_NAME_FLAG_MIN_VERSION = 2.1.224`: that is the messaging release, the flag's
+presence there was verified against the installed 2.1.224 binary, and the version
+comes from `getClaudeCliVersion()` (null on probe failure and under vitest), so an
+older or unknown CLI gets a command byte-identical to before. That matters because
+claude aborts startup on an unknown option, which would kill every session spawn.
+The value is allowlist-sanitized (Unicode letters/digits plus ` ._:-`, leading
+dashes stripped so it cannot parse as another option, 64-char cap, empty result =
+flag omitted) before the double-quoted interpolation in `buildSpawnCommand`, and
+only the LOCAL command carries it: the docker/remote builders never see it, since
+their CLI is not the binary the probe measured. E2E on an isolated instance
+(`CODEMAN_INSTANCE`): process cmdline `claude ... --name w9-msgtest`, registry
+`name: "w9-msgtest"`, `ListAgents` lists it under that name, a message round-trip
+works, and its replies arrive tagged `from-name="w9-msgtest"` (a derived-name
+worker's replies carry no `from-name`). A quick-start without `sessionName` has an
+empty Codeman name, so the peer name stays derived: agents should name their
+workers. Tests: `test/name-flag-injection.test.ts`.
+
+Later narrowing: `--name` is not only the peer name but also the `/resume` picker
+entry and the terminal title, and a pinned title stops Claude generating its own, so
+pinning the `w1-myapp` placeholder listed every conversation of a case under the same
+name in `/resume`. Only a manual name is pinned now (`Session.cliPinnedName`,
+`nameSource === 'manual'`, carried to the builders as `cliName`); placeholder and auto
+names leave Claude to title the conversation. A rename in Codeman appends a
+`custom-title` row to the conversation's transcript (`claude-session-title.ts`), the
+row `/rename` writes. Tests: `test/claude-resume-title.test.ts`,
+`test/routes/session-name-routes.test.ts`.

docs/api-reference.md

@@ -46,6 +46,20 @@ payload return `{ "success": true, "data": {} }`.
 > `GET /api/screenshots/:name`, `GET /q/:code` (QR redirect), and the
 > `GET /ws/sessions/:id/terminal` WebSocket upgrade.
 
+> The [agent wait endpoints](#long-polling-agent-wait) use the normal envelope but
+> are the only JSON endpoints that deliberately **hold the connection open**, for up
+> to 600 s. Proxy operators and HTTP clients with a global read timeout need to know
+> that before pointing them at Codeman.
+
+⚠️ **A `401` is the one status that is not an envelope.** Authentication is rejected
+in a request hook, before any handler runs, and it replies with the bare string
+`Unauthorized` (`Unauthorized: hook secret required` on the hook path) plus
+`WWW-Authenticate: Basic realm="Codeman"`. There is no `success`, no `error`, and no
+`errorCode`, because the wrapping hook only wraps object payloads. So a client that
+pipes every response straight into a JSON parser dies with a parse error rather than
+reporting an auth failure, which is a confusing way to discover that a password is
+set. Branch on the HTTP status **before** parsing.
+
 ## Error codes → HTTP status
 
 The single source of truth is `ErrorStatus` / `httpStatusForErrorCode()` in
@@ -66,6 +80,661 @@ the HTTP status.
 
 Adding a new error code is non-breaking; removing or renaming one is a major change.
 
+## Long-polling (agent wait)
+
+Three calls block until something happens instead of answering immediately. They
+exist because SSE is Codeman's only other "tell me when" channel, and an agent
+driving the API from a shell tool cannot practically hold a stream and parse
+events inline.
+
+| Call | Blocks until |
+|------|--------------|
+| `GET /api/v1/sessions/:id/wait` | one of a set of lifecycle signals fires |
+| `GET /api/v1/sessions/:id/wait-output` | a literal string appears in the session's output |
+| `POST /api/v1/sessions/:id/input` with `wait` | the input is delivered **and then** a signal fires |
+
+`POST .../input` with `wait` is not the same as a `POST` followed by a separate
+`GET .../wait`. It registers the waiter **before** writing, which closes the window
+in which a separate wait sees the session still idle from the previous turn and
+answers instantly with the wrong turn's result. Use it whenever you send a prompt
+and want to know when that prompt is done.
+
+### Three semantics that break callers who assume otherwise
+
+**1. A timeout is HTTP `200`, not an error.** A wait that ends without its signal
+returns `{"success":true, ...,"wait":{"timedOut":true,"signal":null}}`. The
+intended pattern is a client-side loop over short waits, because `tailscale serve`
+and cloudflared can both cut an idle connection, and turning every poll boundary
+into a `4xx` would make that loop indistinguishable from a real failure. `408` is
+auto-retried by several clients (silently doubling the polling load), `504` is what
+a genuine tunnel failure looks like, and `204` cannot carry `waitedMs` / `status` /
+`limitPaused`. Reserve error handling for the four codes in the table below.
+
+**2. `stop` and `blocked` fire only for `claude` sessions.** Both come from Claude
+Code hooks, and no other mode installs them: `shell` runs no agent, and the external
+CLIs (`opencode`, `codex`, `gemini`, `antigravity`, `pi`) render their own TUIs and post
+no hooks. For every non-`claude` mode only `idle`, `working` and `exit` are
+accepted, and of those only `exit` is dependable: see the caveats under
+[Signals](#signals) before building on `idle`. Requesting `stop` or `blocked`
+**explicitly** on such a session is a
+`400`; omitting `until` never fails, the server just drops them from the default set
+and echoes the narrowed set back as `wait.until`. Three more places hooks can go
+missing even in `claude` mode: a **Docker case** needs
+`CODEMAN_DOCKER_BRIDGE_HOOKS=1`, since a container cannot reach a loopback-bound
+Codeman (without it, only `idle` / `working` / `exit` work); a **remote-SSH
+case** runs the agent on another host, whose hooks may never reach this server at
+all; and a case whose hook config was written by **Codeman < 1.13.0 against an
+`--https` install** carries hook curls without `-k`, which TLS-fail silently (the
+hook line ends in `|| true`). Codeman now writes `curl -sk` and repairs a stale
+case config the next time a session starts in that case. When in doubt, ask for
+`stop,idle,exit` so a session without hooks still resolves on the heuristic
+signal.
+
+**3. `from=now` does not mean "printed after you asked".** tmux repaints the visible
+screen on attach, on resize, and on any TUI redraw, and a repaint arrives as
+ordinary output, so text that was already on screen can satisfy a fresh wait. This
+was observed live: a marker echoed a minute earlier matched instantly on a new
+`from=now` wait. It is inherent to running the agent under a multiplexer, so the
+contract is a **marker unique to each call** (`MARK="DONE_$RANDOM"`, send
+`echo $MARK`, then wait on `$MARK`), never a generic string like `BUILD OK`.
+
+### Signals
+
+| Signal | Source | Actually fires for |
+|--------|--------|--------------------|
+| `idle` | the session's own `idle` event | `claude`: yes, on ❯-prompt detection after activity. `shell`: **once only**, ~500 ms after start, and never again. External CLIs: not guaranteed (they render their own TUIs and readiness is output stabilization) |
+| `working` | the session's own `working` event | `claude` only in practice (spinner and work-keyword detection are Claude output formats) |
+| `stop` | the Claude Code `stop` hook, the definitive end-of-turn signal | `claude` only |
+| `blocked` | a `permission_prompt` or `elicitation_dialog` hook | `claude` only, and rarer than it looks: see below |
+| `exit` | no process is behind the session | every mode |
+
+`stop` is the signal to orchestrate on where it exists; `idle` is a heuristic
+fallback that can flap mid-turn when a spinner pauses. The default set when `until`
+is omitted is `stop,idle,exit` (`exit` is in there so a worker that crashes resolves
+the wait promptly instead of burning the caller's whole timeout on something that
+can no longer happen). On a `claude` worker, prefer an explicit `until=stop,exit`
+once the session is up: the default set's `idle` also resolves on a spinner pause,
+and on a fresh session the **startup** `idle` (emitted when the CLI first comes up)
+can land inside your first wait window and report a turn that never ran. Measured:
+a session parked on the trust dialog emits no *further* `idle`, so it is the
+startup transition, not the dialog, that produces the false success below.
+
+⚠️ **`exit` means "nothing is running", which includes "not started yet".** The
+server answers from `pid === null` plus a mux-layer pane-death probe, and that
+covers a session that exited — including a worker that died *inside* its tmux pane
+while the local attach client (and therefore `pid`) lives on — one that was
+detached, and one that was **created but never started**. So the first wait
+after `POST /api/v1/sessions` returns `{"signal":"exit","immediate":true}` in
+milliseconds, and reading that as "the worker died" is wrong: it means start it, or
+wait for it to come up. `status` is carried alongside so nothing is hidden. The
+alternative (trusting `status`) is worse, because a dead PTY parks the session at
+`status: "idle"`, which would answer the default wait with `immediate: true` for a
+worker that has crashed. A worker dying while a wait is parked resolves it within
+a few seconds (a background death-watcher), not at the timeout.
+
+⚠️ **`blocked` is reachable less often than the table suggests.** It fires on two
+hooks, and the default configuration suppresses one of them: Codeman spawns claude
+with `--dangerously-skip-permissions`, so permission prompts do not happen unless the
+instance is switched to the `auto` Claude mode (App Settings), or the caller is a
+multi-user account without the bypass grant, which is forced to `--permission-mode
+auto`. What does still fire under the default is `elicitation_dialog`, the agent
+asking the user a question. So `until=stop,blocked,exit` is a reasonable belt on a
+long turn, but a worker that never comes back is far more likely to be working than
+blocked, and polling `blocked` alone will sit at its timeout.
+
+⚠️ **On a `shell` session, only `exit` and marker-matching are dependable.** A shell
+session emits its one `idle` at startup and then stays `status: "idle"` forever,
+whatever the pane is doing, so it never emits a *transition*. Since send-and-wait
+requires a transition (and so does `fresh=1`), both can only time out there:
+a documented default `wait` on a shell worker running `sleep 4` times out at the
+full 25 s. Synchronize hook-less sessions with `wait-output` and a unique marker
+instead. The same caution applies to the external CLIs.
+
+### Readiness is not a signal
+
+Nothing here reports "the agent is ready for a prompt", and no combination of
+`until`/`fresh` synthesizes one. A freshly created session reads as `exit` (above),
+and a `claude` worker in a brand-new case comes up on the CLI's **trust dialog**,
+which contains a ❯ prompt of its own. Send-and-wait posted at that moment types the
+prompt into the dialog, where the `\r` never gets past it, while the session's
+startup `idle` lands inside the wait window: the wait resolves on `idle` in a
+couple of seconds with `timedOut: false`, which looks exactly like a completed
+turn.
+
+The reliable sequence is: poll `GET /api/v1/sessions/:id` until `.data.pid` is
+non-null, then `wait-output` for the composer's own marker (`bypass`, the status
+bar of a CLI spawned in bypass mode) with a short timeout, handling the trust
+dialog only as the bounded fallback.
+
+⚠️ **The fallback is not a bare `\r`.** Claude Code 2.1.252 unnumbered the dialog's
+options, reversed them and highlights `No, exit`, so an Enter sent blind quits the
+CLI and the pane dies seconds after the spawn. Read the `❯` marker off the current
+frame (`GET /api/v1/sessions/:id/terminal?full=1`), send `ESC [ B` while it is on
+`No, exit`, re-read, and confirm only once it is on `Yes, I trust this folder`.
+Reading the current frame is also what keeps this correct on later runs: the dialog
+text stays in the terminal buffer for the life of the session, so a `trust` probe
+with `from=buffer` keeps matching long after the dialog is gone. A worked version is in
+[`extending-codeman.md`](extending-codeman.md#seam-3-http-api-and-cli).
+
+### `GET /api/v1/sessions/:id/wait`
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `until` | comma-separated list of `idle,working,stop,blocked,exit` | `stop,idle,exit` | resolves on the first to fire. An unknown token is a `400` naming it, never a silent fallback |
+| `timeout` | positive integer ms | `60000` | **validated first, clamped second.** `0`, a negative value and a fractional value are all `400`s, not clamps; a valid value outside `[1000, 600000]` is clamped and echoed as `wait.timeoutMs` |
+| `fresh` | `0` \| `1` \| `false` \| `true` | `0` | `1` requires an actual transition, ignoring the state at call time |
+
+```bash
+curl -s "$API/api/v1/sessions/$SID/wait?until=stop,exit&timeout=60000"
+```
+
+Both GET wait routes answer with `Cache-Control: no-store`, because the documented
+pattern polls one identical URL in a loop and a cached `{"timedOut":true}` would
+turn that loop into a busy spin. `POST .../input` sends no cache header (it is a
+POST, which is not heuristically cacheable).
+
+⚠️ **Unknown query parameters are ignored, not rejected**, with one exception
+(`regex`, below). In particular `match=` on `/wait` is silently dropped and you get
+a plain signal wait, so check the endpoint path before blaming the parameters.
+
+### `GET /api/v1/sessions/:id/wait-output`
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `match` | literal string, 1 to 200 chars | required | substring match against the PTY stream with ANSI escapes stripped. A match spanning two PTY chunks is found |
+| `nocase` | `0` \| `1` \| `false` \| `true` | `0` | case-insensitive compare. The returned snippet keeps the terminal's original casing |
+| `from` | `now` \| `buffer` | `now` | `buffer` scans the tail of the existing terminal buffer (bounded, 256 KB by default) before blocking |
+| `timeout` | positive integer ms | `60000` | same validation and clamp as `/wait` |
+
+**Matching is literal, never a pattern.** A `regex` parameter is rejected with a
+`400` rather than ignored, so a caller that assumed otherwise finds out immediately
+instead of waiting on the wrong thing. The reasoning is in
+[`architecture-invariants.md`](architecture-invariants.md#agent-wait-primitives).
+
+#### What the matcher actually sees
+
+The matcher scans the raw PTY stream, **normalized**: ANSI escape sequences are
+stripped — CSI, OSC, and the charset-designation escapes a stock bash prompt emits
+on every line (`ESC ( B`), so `match=tnode:` matches a prompt that renders
+`…@tnode:` — a partial escape arriving at a chunk boundary is held back until its
+tail arrives, and a match may straddle PTY chunks: `printf STRAD; sleep 1; printf
+DLEQQ` is matchable as `STRADDLEQQ` (all measured live). Three caveats remain:
+
+⚠️ **It is still the byte stream, not the rendered pane.** `GET .../terminal`
+answers from a tmux screen capture (`data.source: "mux-visible"`), the finished
+picture; the matcher sees the stream that painted it. For linear output the two
+agree once escapes are stripped, but a full-screen TUI composes its picture with
+cursor positioning, so what the pane shows and what the stream carries can differ.
+Seeing your string in `terminal?tail=` makes a match likely, not guaranteed.
+
+⚠️ **A TUI's text can arrive without its spaces.** Claude Code positions words
+with cursor moves rather than printing spaces, so screen text can reach the
+matcher as `Quicksafetycheck:Isthisaprojectyoucreated...`. Whether a given phrase
+keeps its spaces depends on how the TUI happened to draw it (measured: `I trust
+this folder` matched, `Quick safety check` did not), so a multi-word `match`
+against a TUI pane is unreliable rather than impossible. Match a **single
+space-free token**, ideally one you printed yourself. Plain command output (a
+shell worker, an `echo`) keeps its spaces.
+
+⚠️ **The returned `snippet` is a rendering of the matched text, not a quotation of
+it.** It is cut from the same normalized stream the match ran against, then
+cleaned for display: remaining raw control bytes are removed (an agent pipes the
+snippet into its own terminal, so a worker's bytes must not be able to reset that
+display) and blank runs are collapsed. A printable needle that matched will appear
+in it; a needle containing control bytes or a blank run may not survive verbatim.
+
+```bash
+MARK="DONE_$RANDOM"
+curl -sG "$API/api/v1/sessions/$SID/wait-output" \
+  --data-urlencode "match=$MARK" --data-urlencode 'timeout=120000'
+```
+
+Build the query with `-G --data-urlencode` rather than by hand: a `+` in a
+hand-written query string decodes to a space.
+
+### `POST /api/v1/sessions/:id/input` with `wait`
+
+Two optional fields on the existing endpoint:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `wait` | `true` or the same comma grammar as `until` | `true` means the default signal set. Omitted keeps the historical fire-and-forget behavior, unchanged. `null`, `false` and an empty string are all read as **absent**, not as an error and not as "wait for the default" |
+| `waitTimeout` | positive integer ms | same validation **and** clamp as `timeout`: `0`, a negative and a fractional value are `400`s, anything valid is clamped into `[1000, 600000]` and echoed as `wait.timeoutMs` |
+
+Both are `nullish`, so an explicit `null` from `JSON.stringify` is accepted as
+"absent" rather than failing validation. That is deliberate: `.optional()` would
+reject it, which has shipped as a real bug twice.
+
+The input must end with `\r` (a real carriage return in the JSON string): Enter is
+sent only when the input contains one, so text without it is typed onto the
+worker's prompt but never submitted, and the wait then runs its full timeout on a
+turn that never started. Verified live; this is the most common silent failure on
+this endpoint.
+
+A **plain prompt** (printable text followed by exactly one `\r`, nothing else) is
+delivered through tmux even without `useMux`: the text is typed, Enter is pressed as
+a separate key, and the server re-presses Enter while the prompt is still visibly
+sitting on the composer. Written straight into the pane in one piece, a prompt of
+about a hundred characters or more is taken as a paste by Claude Code, its `\r`
+becomes a newline, and the prompt stays unsent (measured on 2.1.283). Any other
+input (escape sequences, a bracketed-paste frame, a line feed, a bare `\r`) keeps
+the raw write, and an explicit `"useMux": false` forces it.
+
+```bash
+curl -s -X POST "$API/api/v1/sessions/$SID/input" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"run the tests\r","useMux":true,"clientId":"agent-1","seq":1,
+       "wait":"stop","waitTimeout":600000}'
+```
+
+A **tagged duplicate** (a `clientId` + `seq` pair the server has already applied)
+still honors `wait`, because the caller's question is unanswered, but it answers
+from the session's current state rather than requiring a new transition: the
+original turn may be long over. It comes back as
+`"delivered": false, "duplicate": true`.
+
+**Wake-on-LAN hosts** (`docs/remote-sessions.md` §Wake-on-LAN): when the session's
+remote host has a wake target and is asleep, the non-wait form answers `200` with
+`{"buffered": true}` — the bytes are held and flushed after the host is back — or
+`{"buffered": true, "dropped": true}` for a chunk over the 4 KB wake buffer, which
+is gone (never delivered as a fragment). Both fields are additive to the historical
+bare `{}`. With `wait`, the route blocks on the wake instead and answers
+`422 OPERATION_FAILED` ("did not come back after a wake-on-LAN request — nothing was
+sent") when the host never returns, rather than writing into the stalled pane and
+reporting `delivered:true` plus a timeout.
+
+Two endpoints back that flow directly, both scoped to one session's remote host and
+both refusing a session that is not remote (`400 INVALID_INPUT`):
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/api/sessions/:id/reachability` | Whether the session's remote host answers SSH right now, plus whether a wake target is configured. Read-only: it never wakes. `{"reachable": true\|false\|null, "wakeConfigured": "mac"\|"command"\|"none"}`, where `null` means the answer is unknown (a proxied host, where a TCP probe proves nothing). |
+| `POST` | `/api/sessions/:id/wake` | Wake the host and wait for it to accept SSH again, bounded by the request budget. `422 OPERATION_FAILED` when it does not come back; `400 INVALID_INPUT` with "No wake-on-LAN target configured for this host" when nothing is set. |
+
+⚠️ Waking is deliberately reachable only from an explicit user action (this route, a
+session create/attach, or typing into a sleeping session). No watcher, dropped-session
+handler or boot-recovery path may wake a host, or a suspended machine would be woken
+again seconds after every suspend; `test/remote-wake.test.ts` pins that as an import
+fence around `src/remote-wake.ts`.
+
+### Response
+
+All three nest the wait result under `data.wait`, so one client helper works against
+any of them:
+
+```json
+{ "success": true, "data": {
+  "sessionId": "28325fd3-caa7-4178-82bf-87dfebf0f464",
+  "status": "idle",
+  "limitPaused": false,
+  "wait": {
+    "signal": "stop", "until": ["stop", "idle", "exit"],
+    "timedOut": false, "immediate": false, "ended": false, "aborted": false,
+    "waitedMs": 8421, "timeoutMs": 60000
+  }
+}}
+```
+
+`POST .../input` returns the same `wait` object alongside `delivered`, `duplicate`,
+`status` and `limitPaused`. `POST .../input` **without** `wait` is unchanged and
+still returns `{"success": true, "data": {}}`.
+
+⚠️ `delivered: false` has **two** meanings, and they must be told apart by
+`duplicate`: with `duplicate: true` the input was suppressed as an already-applied
+redelivery (harmless, the turn it refers to may be long over), while with
+`duplicate: false` the **write failed** (typically no PTY behind the session). A
+client that reads `delivered === false` as "duplicate" silently treats a failed send
+as a success.
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `wait.signal` | signal \| `null` | the signal that fired (`/wait` and `/input` only) |
+| `wait.until` | array of signals | what the server actually waited on, after narrowing the default set for the session's mode (`/wait` and `/input` only) |
+| `wait.matched` | boolean | the string appeared (`/wait-output` only) |
+| `wait.match` | string | the literal that was searched for (`/wait-output` only) |
+| `wait.snippet` | string \| `null` | bounded window of output around the match, blank runs collapsed for readability (`/wait-output` only) |
+| `wait.timedOut` | boolean | the wait hit its timeout. Still a `200` |
+| `wait.immediate` | boolean | the condition already held at call time, so nothing was waited for (`waitedMs` is 0) |
+| `wait.ended` | boolean | the session went away (deleted or torn down) before the condition was met |
+| `wait.aborted` | boolean | the client hung up, so the waiter was released without resolving — and by that definition a client never reads `true`. When the **server** abandons a wait itself (send-and-wait against a session with no PTY), it answers in about a millisecond with `ended: true`, `delivered: false`, `duplicate: false` and `aborted: false`: `delivered`/`ended` carry that story, and `aborted` stays the transport flag. Present for completeness; treat a `true` as "this wait answered nothing", never as an outcome |
+| `wait.waitedMs` | number | wall-clock ms actually spent waiting |
+| `wait.timeoutMs` | number | the timeout **after clamping**, which is what was applied |
+| `status` | `SessionStatus` | the session's status after the wait, so a caller that timed out still learns where things stand |
+| `limitPaused` | boolean | the session is paused on a usage limit and will emit nothing until its reset, so a timeout here is expected rather than a stall worth retrying hard |
+
+Read the outcome by discriminator, in this order:
+
+1. `wait.signal !== null` (or `wait.matched === true`): the thing happened.
+2. `wait.timedOut`: a poll boundary. Loop again.
+3. `wait.ended` or `wait.aborted`: the wait answered nothing, because the session is
+   gone or was never running. Re-check the session instead of looping.
+
+`wait.immediate` is not a fourth outcome: it rides along with the first one and
+means the condition already held at call time, so nothing was actually waited for.
+If that is not what you meant, you wanted `fresh=1` or the send-and-wait form. Note
+that `{"signal":"exit","immediate":true}` on a session you just created is the
+not-started-yet case, not a crash.
+
+**The timeout is clamped, so read it back.** A request for 1800000 ms is silently
+reduced to the server's ceiling (600000 ms by default, operator-tunable), and a
+request for 1 ms is raised to 1000 ms. `wait.timeoutMs` is the value that was
+applied. Without checking it, a caller that asked for 30 minutes and got 10 will
+read the timeout as "the worker is wedged" and kill a session that was working fine.
+
+### Errors
+
+| `errorCode` | HTTP | When |
+|-------------|------|------|
+| `INVALID_INPUT` | 400 | unknown `until` / `wait` token; `stop` or `blocked` requested explicitly on a mode that installs no hooks (the message names the mode); `regex=` on `/wait-output`; `match` outside 1 to 200 chars; a non-numeric `timeout` |
+| `NOT_FOUND` | 404 | no such session, or one this caller does not own |
+| `SESSION_BUSY` | 409 | this session's waiter cap is full |
+| `RATE_LIMITED` | 429 | a per-owner or process-wide waiter cap is full. Retry later; the session you named is not the problem |
+
+The two capacity codes are deliberately different. A process-wide cap reported as
+`SESSION_BUSY` would tell the caller to switch sessions, which cannot help. The
+error message names the cap that was hit.
+
+⚠️ A `401` is **not** in this table and is not an envelope at all (see
+[Response envelope](#response-envelope)). It matters most here: a polling loop that
+pipes each wait straight into `jq` fails with a parse error on every iteration
+against a password-protected server, which reads as "the wait endpoints are broken".
+Check the status first.
+
+The per-session cap is a **combined** budget: signal waiters and output waiters
+count against the same 16, not 16 of each. An abandoned request no longer holds its
+slot, because the routes release the waiter when the client disconnects, but a
+client that opens many concurrent waits against one session will still hit the cap.
+
+## Session lineage (`parentSessionId`)
+
+A create request may name the session that spawned it, which the web UI draws as a
+line between the two tabs. Accepted on `POST /api/v1/sessions` and
+`POST /api/v1/quick-start`, either way:
+
+```bash
+# as a body field
+-d '{"caseName":"worker-1","mode":"claude","parentSessionId":"'"$CODEMAN_SESSION_ID"'"}'
+
+# or as a header, which is what an agent driving many spawns should use: set it once
+# on the curl invocation and every spawn call carries it
+-H "X-Codeman-Parent-Session: $CODEMAN_SESSION_ID"
+```
+
+The body field wins if both are present. The value is resolved against live sessions
+(exact id, or a unique prefix of at least 8 characters) and must belong to the same
+owner as the session being created.
+
+**It cannot fail your spawn.** An unknown, stale, foreign or malformed value is
+silently dropped and the session is created without lineage — never a `400`. It is
+also pure decoration: it confers no permission, and a child is unaffected by its
+parent exiting. It appears on session state as `parentSessionId` (absent when
+unresolved) and survives a server restart.
+
+## Approvals Inbox
+
+Cross-session queue of prompts waiting on a human (permission dialogs,
+AskUserQuestion questions, idle prompts). Claude-mode sessions only; items are
+in-memory (a server restart drops them; the next prompt re-fires the hook).
+Design: [`approvals-inbox-plan.md`](approvals-inbox-plan.md).
+
+- `GET /api/v1/approvals` → `{ approvals: ApprovalItem[] }`, oldest first,
+  ownership-scoped in multi-user mode. `ApprovalItem`: `{ id, sessionId,
+  sessionName, kind: 'permission'|'question'|'idle', createdAt, toolName?,
+  toolSummary?, message?, cwd?, context?, options?: {n, label}[],
+  acknowledgedAt? }`. `context` is the ANSI-stripped visible pane frame;
+  `options` is present only when the dialog's numbered choices parsed
+  confidently; `acknowledgedAt` marks an item a human has already looked at
+  (see `/viewed` below) and tells clients not to re-arm its tab alert. Listing
+  also runs a staleness sweep over the caller's own items: the pane is
+  re-captured, and an item whose dialog no longer parses is resolved as
+  `resolved_in_terminal` instead of being returned (only items whose original
+  frame parsed `options` can be dropped this way, so an unreadable capture
+  keeps the item).
+- `POST /api/v1/approvals/:id/answer` with `{ action: 'approve' }` (sends the
+  digit `1`), `{ action: 'deny' }` (sends Esc), `{ action: 'option', option: n }`
+  (sends the digit; accepted only when `n` is among the item's parsed
+  `options`), or `{ action: 'text', text }` (idle prompts only; submits the
+  line as a prompt). `404 NOT_FOUND` when the item is no longer pending,
+  `409 CONFLICT` when the dialog left the screen or another actor answered
+  first, `422 OPERATION_FAILED` when the session refused input.
+- `POST /api/v1/approvals/:id/dismiss` removes the item without keystrokes.
+- `POST /api/v1/approvals/session/:sessionId/viewed` → `{ sessionId,
+  acknowledged: itemId | null }`. Marks the session's pending **idle** item as
+  seen by a human (the web UI calls it when you open the session's tab): the
+  item stays pending and answerable, but stops arming the yellow tab alert on
+  every client, including after a reload. Permission/question items are never
+  acknowledged this way, since looking at a dialog does not answer it. `404`
+  for an unknown or inaccessible session; acknowledging twice is a no-op
+  (`acknowledged: null`).
+
+SSE events: `approval:pending` (full item), `approval:updated` (context/options
+re-captured, or the item acknowledged), `approval:resolved` (`{ id, sessionId, kind, resolution }` with
+`resolution` one of `answered | resolved_in_terminal | superseded |
+session_ended | dismissed | expired`).
+
+## Reboot restore
+
+A host reboot takes the tmux server down with it, so every pane dies and the
+board comes up empty. At boot Codeman works out which sessions the reboot
+destroyed and holds that plan in memory, and these endpoints let a client offer
+it to the user. Nothing creates a pane until the user asks: the boot-time reboot
+heuristic decides whether to ASK, never whether to act.
+
+Claude-mode sessions only (others carry their conversation id in their own
+config object); remote and docker sessions are never offered, because both need
+another host or container to be up. The plan is in-memory, so a server restart
+drops it and the offer is gone; the conversations themselves are unaffected,
+since they live in the CLI's own transcript store and stay reachable from the
+Resume list. A plan nobody spends expires after 24 hours.
+
+- `GET /api/v1/reboot-restore` → `{ sessions: RestorableSession[],
+  scrollbackRestored: false }`, ownership-scoped in multi-user mode.
+  `RestorableSession`: `{ id, name?, workingDir, mode, owner? }`. The persisted
+  record itself is never sent. `scrollbackRestored` is always `false` and exists
+  so a client states it: a restored session is a NEW pane, so the conversation
+  continues and the terminal history does not.
+- `POST /api/v1/reboot-restore/restore` with `{ sessionIds?: string[] }` (omit
+  to restore everything the caller can see) → `{ restored: RestorableSession[],
+  skipped: { sessionId, reason }[] }`. `reason` is one of `workspace-missing`
+  (the directory is gone), `workspace-forbidden` (in multi-user mode it is
+  outside the workspace of the user the session belongs to, re-checked against
+  that owner's current grant rather than the caller's), `already-live` (the conversation is already
+  open, typically resumed by hand from the Resume list), `capacity-reached`
+  (the global or per-user session cap), or `rebuild-failed` (the agent would not
+  start, most often a CLI binary missing from the server's PATH).
+  `409 CONFLICT` when that caller already has a restore running. Entries are
+  removed from the plan before any pane is built, so a double-click cannot put
+  two panes on one conversation; anything that never became a pane goes back on
+  offer, except `already-live`, which cannot stop being true. A restored session
+  comes back attached, idle and disarmed: respawn controllers and Ralph loops
+  are never re-armed automatically.
+- `POST /api/v1/reboot-restore/dismiss` → `{ dismissed: n }`. Drops the offer
+  for everything the caller can see.
+
+Each rebuilt session also emits the ordinary `session:created` SSE event, so
+clients other than the one that clicked pick it up without refetching.
+
+## Read My Mind intent profiles
+
+Per-case profiles of what the user is trying to accomplish: user/agent-stated
+goals plus the user's recently submitted prompts, captured from the Claude
+session transcript while the opt-in `readMyMindEnabled` setting is on (default
+OFF). Keyed by owner + workingDir, so the profile survives `/clear`, respawns,
+and session churn. Stored in `~/.codeman/intents.json` (mode 0600); never fed
+into `/api/v1/search`. Design: [`readmymind-plan.md`](readmymind-plan.md);
+user guide: [`readmymind.md`](readmymind.md).
+
+- `GET /api/v1/sessions/:id/intent` -> `{ intent: IntentProfile }` for the
+  session's case. `IntentProfile`: `{ key, workingDir, updatedAt, goals,
+  recentPrompts: { ts, sessionId, text }[] }` (prompts oldest first, FIFO cap
+  50, each <= 500 chars). A case with nothing recorded answers an empty
+  profile with `updatedAt: 0`; nothing is persisted by reads.
+- `PUT /api/v1/sessions/:id/intent` with `{ goals }` (<= 8192 chars, strict
+  schema) replaces the goals text and answers the updated profile.
+  `400 INVALID_INPUT` on over-long or unknown fields.
+- `DELETE /api/v1/sessions/:id/intent` -> `{ deleted: boolean }` forgets the
+  case's profile entirely.
+- `POST /api/v1/sessions/:id/readmymind` predicts the user's next prompt:
+  a one-shot model call over the intent profile plus live session signals
+  (pending approval dialog, transcript tail, git state, run-summary events,
+  sibling sessions). Body is optional; the rethink flow passes
+  `{ steer?, rejected? }` (strict schema: `steer` <= 2000 chars, `rejected`
+  up to 10 strings <= 1000 chars). Answers
+  `{ suggestions: { prompt, why, kind }[], durationMs }` with 1-3 suggestions
+  (`kind`: `continue` | `verify` | `redirect`; prompts are single-line).
+  Claude-mode sessions only (`400 INVALID_INPUT` otherwise); one prediction in
+  flight per session (`409 CONFLICT`); predictor failures answer
+  `502 OPERATION_FAILED`. Takes 5-90 s and costs real tokens. Suggestions are
+  only ever returned, never sent: submitting one is the caller's explicit act.
+
+All four enforce session ownership in multi-user mode; a foreign session id
+answers `404 NOT_FOUND` (no existence leak), and profiles of two owners of the
+same directory are distinct by construction.
+
+## Custom Model Endpoints
+
+Points a session's harness at a user-configured OpenAI-compatible endpoint —
+local (llama.cpp, vLLM, DGX Spark) or cloud (Azure AI Foundry, OpenRouter) —
+instead of its native cloud backend, gated by the opt-in
+`customModelEndpointsEnabled` setting (default OFF). Endpoints are
+machine-level infra, like remote/docker hosts: writes are admin-only in
+multi-user mode. Design: [`custom-model-endpoints-plan.md`](custom-model-endpoints-plan.md);
+user guide: [`custom-model-endpoints.md`](custom-model-endpoints.md).
+
+- `GET /api/v1/model-endpoints` -> `CustomModelHost[]`, an unwrapped bare
+  array like every other list route (still riding the standard `{success,
+data}` envelope on the wire — unwrap it the same way). Answers `[]` for a
+  non-admin in multi-user mode. `apiKey` is never returned; `apiKeySet:
+boolean` reports whether one is stored, so a client can render "unchanged
+  if left blank" without ever holding the real value.
+- `POST /api/v1/model-endpoints` with `{ id, label, baseUrl, apiKey?,
+authStyle?, defaultModelId? }` creates one. `id` must match
+  `^[a-zA-Z0-9_-]+$`; `authStyle` is `bearer` (default) or `api-key`, never
+  both (a real server hung indefinitely when sent both headers on one
+  request); `baseUrl` must be `http(s)`, carry no embedded credentials, and
+  is refused if it points at (or resolves to) a link-local or
+  cloud-metadata address. `409 ALREADY_EXISTS` on a duplicate id.
+- `PUT /api/v1/model-endpoints/:id` updates one. An **absent** `apiKey`
+  keeps the stored one rather than clearing it — the client never receives
+  the real value to resend deliberately unchanged, so omission is the only
+  way to say "leave it alone"; there is no way to clear a key back to unset
+  this way. `defaultModelId`, when set, must be one of that endpoint's own
+  `models` (`400 INVALID_INPUT` otherwise).
+- `DELETE /api/v1/model-endpoints/:id` removes one.
+- `POST /api/v1/model-endpoints/:id/discover-models` fetches the endpoint's
+  own `GET /v1/models` and stores the result as `models`, updating
+  `lastDiscoveredAt`, plus (best-effort, only for a model llama-swap's own
+  response already reports loaded) `modelContextLengths` and `modelSizesGB`.
+  A `defaultModelId` that no longer appears in the fresh list is dropped
+  rather than carried forward invalid. Failures answer `422 OPERATION_FAILED`
+  with the underlying connection error, or a named egress refusal if the
+  resolved address turned out to be blocked. The same refresh also runs
+  automatically for every saved endpoint every 5 minutes in the background
+  (`refreshAllCustomModelHosts()`, `custom-model-routes.ts`, started from
+  `server.ts`), so there is no route for triggering "refresh all" — one
+  endpoint being unreachable on a cycle never blocks the others.
+- `GET /api/v1/model-endpoints/:id/running-status` -> `{ isLlamaSwap,
+running: [{model, state}], logLine? }`, read-only, no admin gate
+  (any session owner who could already point a session at this endpoint can
+  equally ask what it currently has loaded). `isLlamaSwap` is
+  feature-detected via the endpoint's own `GET /running` — a plain
+  llama.cpp/OpenAI-compatible server has none and always answers `false`.
+  `logLine`, present only when `isLlamaSwap` is true, is the most recent
+  REAL backend `llama-server` process log line (`load_model: ...`,
+  `llama_server: model loaded`, etc.), sourced from the endpoint's own
+  `GET /api/events` SSE stream and filtered to `source: "upstream"` frames
+  only (never llama-swap's own `source: "proxy"` request-access log) — one
+  connection is held open per endpoint and reused across every poller,
+  idle-closed after 30s of nobody asking. This is what the Run-menu
+  picker's loading banner polls once a second while a model is loading.
+- `POST /api/v1/sessions/:id/custom-model` with `{ endpointId, modelId,
+confirmed? } | { clear: true }` applies (or clears) the session's
+  selection and **restarts the session's CLI process in place** — every
+  supported harness reads its endpoint config at process start, never per
+  turn, so there is no live hot-swap. (`POST /api/v1/quick-start`'s own
+  `customModel: { endpointId, modelId, confirmed? }` field is the
+  no-restart equivalent for a session that doesn't exist yet — see below.)
+  A Claude session resumes its existing conversation across the restart;
+  pi/omp/grok additionally get a forced `--model`/`-m` value, since for
+  those three the config file alone does not select it. `400 INVALID_INPUT`
+  for a remote (SSH) or Docker session — both restart their agent
+  differently under the hood, and applying to one would report success
+  while changing nothing. Two more responses replace the normal
+  `{customModel, restarted}` shape, neither an error, and neither restarts
+  or creates anything on the first ask. ⚠️ **Each is answered by its OWN
+  flag on the retry, and answering one is not consent to the other**: they
+  are questions about different people, and while they shared a single flag
+  a caller who confirmed the context warning silently agreed to evict
+  another session's model as well. Send `confirmedContext: true` to proceed
+  past the context warning, `confirmedSwap: true` past the swap conflict,
+  and both when both were asked (they accumulate, so the second retry still
+  carries the first answer). The original `confirmed: true` still means
+  BOTH and is still accepted, because it shipped in this feature's
+  HTTP-API-only cut; new callers should send the specific one:
+  - `{requiresConfirmation: true, currentlyLoadedModel, affectedSessions}` —
+    llama.cpp/llama-swap only runs one model at a time, and switching would
+    unload a model another **live session's own selection** is actively
+    using. Never returned for a plain (non-llama-swap) server, and never
+    just because a swap is needed at all — only when it would disrupt
+    someone else.
+  - `{requiresContextWarning: true, modelId, contextLength,
+minSafeContextTokens}` — Claude Code's own fixed per-turn overhead
+    (system prompt + tool schemas) can exceed a small model's entire
+    discovered context on its own, before any conversation history exists
+    to compact, guaranteeing the very first message fails regardless of
+    `CLAUDE_CODE_MAX_CONTEXT_TOKENS`. Gated on the CLI registry declaring a
+    `contextLengthVar` (claude only today), so it never fires for another
+    harness.
+- `POST /api/v1/quick-start`'s `customModel: { endpointId, modelId,
+confirmed?, confirmedContext?, confirmedSwap? }` field (alongside its
+normal `caseName`/`mode`/etc. body)
+  computes the same injection **before** the session exists and launches
+  directly on the endpoint — no restart, because there was never a
+  native-backend boot to restart away from. Runs the identical checks as
+  the dedicated route above (`requiresConfirmation`/`requiresContextWarning`,
+  same shapes, same per-question `confirmedContext`/`confirmedSwap` retry),
+  and is refused the same way
+  for a remote or Docker case. This is what the Run-menu picker uses for
+  opencode, Codex, Gemini, Pi, Grok, DeepSeek and OMP; Claude still uses the
+  dedicated restart route above (its `--resume`-based restart is far less
+  jarring than a full relaunch, and folding it into the one-shot path is
+  separate work — see `docs/custom-model-endpoints-plan.md`).
+
+## CLI management
+
+Read and write the CLI registry (`docs/cli-registry.md`). Every **write** route answers `403 FORBIDDEN` while `cliManagementEnabled` is off (the default), and for a non-admin in multi-user mode. A write that would overwrite a `clis.json` which does not parse, or which has group/world permission bits, is refused with `409 CONFLICT` and a message naming the fix; the file is left untouched.
+
+| Method   | Path                          | Body                                                    | Notes                                                                                                   |
+| -------- | ----------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `GET`    | `/api/clis`                   | none                                                    | Every entry, disabled ones included: `id`, `label`, `shortBadge`, `order`, `kind`, `enabled`, `stock`, `installed`, and `installCommand` for a stock entry. Not gated; a non-admin in multi-user mode gets `[]`. |
+| `PUT`    | `/api/clis/:id`               | `{ enabled }`                                           | Toggle an existing entry, stock or custom. `404` for an unknown id; `400 INVALID_INPUT` when disabling a `kind: 'shell'` entry. |
+| `POST`   | `/api/clis/:id/install`       | none                                                    | Run a **stock** entry's install command (never a custom one: `400`). `409 CONFLICT` while an install for the same id is running; `422 OPERATION_FAILED` with the output tail when it fails. Never enables the entry. |
+| `POST`   | `/api/clis`                   | `{ id, label, shortBadge, binaries, argv, enabled? }`   | Create a custom entry. `409 ALREADY_EXISTS` for a stock id or an existing custom id. `enabled` defaults to `true`. |
+| `PUT`    | `/api/clis/custom/:id`        | `{ label, shortBadge, binaries, argv, enabled? }`       | Replace an existing custom entry. An absent `enabled` keeps the entry's current state. `400` for a stock id, `404` for an unknown one. |
+| `DELETE` | `/api/clis/:id`               | none                                                    | Delete a custom entry. `400` for a stock id, `404` for an unknown one.                                  |
+
+## Voice dictation
+
+Browser dictation transcribed through this server's Claude Code login, i.e. the
+same speech-to-text service the CLI's own `/voice` mode uses. Gated on the synced
+`claudeVoiceEnabled` setting (default OFF). Design:
+[`claude-voice-plan.md`](claude-voice-plan.md).
+
+- `GET /api/v1/voice/status` -> `{ available, reason?, subscriptionType?,
+  expiresAt? }`. `reason` is `disabled` (setting off), `no-credentials` (nobody
+  signed in to Claude Code on the server), `expired` (the access token elapsed;
+  running any Claude session refreshes it) or `malformed`. The OAuth token
+  itself is never returned by this or any other endpoint.
+- `GET /ws/voice/stream?language=&keyterms=` (WebSocket, not under `/api`)
+  relays one dictation. Client sends binary frames of signed 16-bit
+  little-endian PCM, 16 kHz mono (<= 64 KB per frame), plus JSON control frames
+  `{"t":"finalize"}` (ask for the final transcript) and `{"t":"stop"}`. Server
+  sends `{"t":"ready"}`, `{"t":"transcript","text","final"}` (each frame is the
+  WHOLE running transcript, not a delta), `{"t":"error","message"}` and
+  `{"t":"closed"}`. Close codes: `4003` disallowed Host/Origin, `4004`
+  unavailable (reason in the close reason), `4008` too many concurrent streams.
+  Streams are capped in count and length (`src/config/voice.ts`).
+
 ## Authentication
 
 Optional HTTP Basic (`CODEMAN_USERNAME`/`CODEMAN_PASSWORD`) → opaque
@@ -82,6 +751,29 @@ the stable contract — event names are not renamed without a major bump. An
 optional `?sessions=<id,...>` filter suppresses only the high-volume terminal
 stream; lifecycle/metadata events are delivered to all clients regardless.
 
+### `sse:heartbeat` (liveness)
+
+Every 15s the server writes a `sse:heartbeat` frame to every connected client:
+
+```
+event: sse:heartbeat
+data: {"t":1755100000000}
+```
+
+`t` is the server's epoch-ms timestamp at write time. The frame carries no
+application state and can be ignored for correctness. It exists so a client can
+tell a live stream from a dead one: an `EventSource` whose connection has been
+idle-closed by a proxy (or that resumed from sleep on a stale socket) keeps
+delivering nothing without ever firing `onerror`. Clients that care should treat
+silence longer than about three intervals as a dead stream and reconnect, which
+is what the bundled frontend does.
+
+This replaced a `:keepalive` SSE **comment**, which served the same
+proxy-flushing purpose but is invisible to `EventSource` by spec and so could
+never be observed by a client. Consumers written against the old behavior are
+unaffected: `EventSource` dispatches only events that have a registered
+listener, so an unknown event name is dropped.
+
 ## Consuming from JavaScript
 
 The bundled frontend reads responses through `_apiJson()`

docs/approvals-inbox-plan.md

@@ -0,0 +1,107 @@
+# Approvals Inbox (design)
+
+One cross-session inbox for every prompt that is waiting on a human: permission dialogs, questions (AskUserQuestion / elicitation), and idle prompts. Cards are answerable in place (option digits, Esc, or a typed prompt) from desktop, phone overview, and push notification action buttons. Inspired by Cloudflare OS's Gatekeeper approval queue (https://github.com/cloudflare/cloudflare-os, asynchronous human-in-the-loop approvals): with a fleet of sessions the human is the bottleneck, and today answering means finding the right tab.
+
+## Problems this fixes (all real today)
+
+1. **No cross-session surface.** Pending prompts exist only as per-tab alert colors (`tab-alert-action`/`tab-alert-idle`) and NEEDS YOU rows on the phone overview. Answering means switching to the session and typing.
+2. **Alerts die on reload.** `pendingHooks` lives only in `app.js` memory, fed by transient SSE `hook:*` events. A page reload (or a phone browser evicting the tab) silently loses every pending alert. There is no server-side record.
+3. **Push Approve/Deny buttons are dead.** `PUSH_EVENT_MAP` already attaches `approve`/`deny` actions to permission pushes, and `sw.js` forwards `event.action` to the page, but the `notification-click` handler in settings-ui.js ignores it (and when no tab is open, the action is dropped entirely). The buttons render on the lock screen and do nothing.
+4. **Card context is missing.** The frontend handlers read `data.question` / `data.message` / `data.tool`, but `sanitizeHookData` never forwards `message`, so notifications show generic fallback text.
+
+## Scope
+
+- Claude mode only (hooks fire only for `claude`; external CLIs keep their output-stabilization heuristics and get no inbox items). This mirrors the wait-primitive `stop`/`blocked` gating.
+- Permission prompts occur for sessions running `ClaudeMode` `normal` / `auto` / `allowedTools` (and the trust-folder dialog even under skip-permissions). Question and idle prompts occur in every mode including `dangerously-skip-permissions`.
+- In-memory store (plus the frontend seeding from it on load). Server restart drops items; hooks re-fire on the next prompt. No new state file in v1.
+
+## Data model
+
+At most **one active item per session**: the Claude TUI shows one dialog at a time, so a new prompt event supersedes the session's previous item (resolution `superseded`).
+
+```ts
+interface ApprovalItem {
+  id: string;                 // `${sessionId}:${seq}`
+  sessionId: string;
+  sessionName: string;
+  kind: 'permission' | 'question' | 'idle';
+  createdAt: number;
+  toolName?: string;          // from sanitized hook data
+  toolSummary?: string;       // command / file_path / description, already bounded
+  message?: string;           // Notification hook `message` (newly allowlisted)
+  cwd?: string;
+  context?: string;           // ANSI-stripped visible pane frame tail, ≤ 4000 chars
+  options?: { n: number; label: string }[]; // parsed from context when confident
+}
+```
+
+Resolutions (server-emitted, item removed from pending): `answered` (via inbox), `resolved_in_terminal` (stop / elicitation_complete / elicitation_response / session went working), `superseded`, `session_ended`, `dismissed`, `expired` (12h TTL sweep).
+
+## Backend
+
+### Store: `src/approval-inbox.ts`
+
+Module-level singleton in the style of `session-wait-registry.ts` (pure, no `Session` import, injected emit callback so there is no import cycle with the server):
+
+- `notePrompt(info)` creates/supersedes the session's item; schedules ONE re-capture ~600ms later (the Notification hook can fire before the dialog finishes painting) which updates `context`/`options` and emits `approval:updated`.
+- `resolveForSession(sessionId, reason)`, `dismiss(id)`, `answerable(id)`, `listPending()`, `stop()` (clears timers; tests).
+- Option parsing (pure, unit-tested): consecutive `❯? N. label` lines, 2..6 options, labels ≤ 120 chars. Parsed options gate which digits the answer endpoint accepts; when parsing fails the card falls back to Approve(1)/Deny(Esc) only.
+- TTL: items expire after 12h (checked on read + a lazy sweep; no standing interval).
+
+### Wiring
+
+- `hook-event-routes.ts`: on `permission_prompt` / `elicitation_dialog` / `idle_prompt`, call `notePrompt` with sanitized data + a pane capture callback (`mux.capturePaneBuffer(muxName)` visible frame, ANSI-stripped via existing utils; fall back to `session.terminalBuffer` tail). On `stop` / `elicitation_complete` / `elicitation_response`, `resolveForSession(id, 'resolved_in_terminal')`.
+- `session-listener-wiring.ts`: `working` listener resolves **idle items only** (`working` is heuristic and can flap mid-turn, so it must never clear a pending permission/question dialog); `exit` resolves with `session_ended`. Same singleton-import pattern as `sessionWaits`.
+- Session delete route: resolve with `session_ended`.
+- **New hook matchers** `elicitation_complete` + `elicitation_response` added to `generateHooksConfig()`, `HookEventType`, `HookEventSchema`, and both SSE registries. `refreshStaleCodemanHooks` gets a staleness probe for them (`hooksJson.includes('elicitation_complete')`) so existing cases heal on next Claude spawn, exactly like the `-k`/secret/marker probes.
+- `sanitizeHookData`: allowlist `message` (bounded 500 chars). This also un-deadens the existing notification text paths.
+
+### Routes: `src/web/routes/approval-routes.ts`
+
+Normal authed API (NOT the hook-secret bypass), `ApiResponse` envelope, Zod schemas in `schemas.ts`:
+
+- `GET /api/approvals` → pending items, multi-user filtered by `canAccessOwned` (same policy as session lists). Also sweeps the caller's own items for staleness through `verifyStillAnswerable()`: Claude Code fires no "permission answered" hook, so a dialog answered in the terminal used to sit pending until `stop` and re-arm a red tab alert on the next page load. Only items whose original frame parsed options can be dropped this way, so an unreadable capture keeps the alert.
+- `POST /api/approvals/:id/answer` body `{ action: 'approve' | 'deny' | 'option' | 'text', option?, text? }`:
+  - `approve` → `writeViaMux('1')` (option 1 is always plain Yes; no Enter, menus react to the digit).
+  - `deny` → `writeViaMux('\x1b')` (Esc is the official No/cancel; precedent: auto-resume sends Esc the same way).
+  - `option` → digit `String(n)`; accepted only when `n` is within the item's parsed options (prevents blind digit-poking at an unparsed dialog).
+  - `text` → `idle` items only: single line, embedded newlines stripped, sent as `text\r` (the `\r` discipline from CLAUDE.md).
+  - Guards: item still pending (404 otherwise), session exists + ownership via `findSessionOrFail`, session mode installs hooks. **Answer-time re-capture**: for items whose frame parsed options, the pane is re-captured before sending; if the dialog no longer parses, the item resolves and the answer is refused with 409 (the keystroke would land in whatever now has focus). Marks `answered` BEFORE the write so a double-tap cannot double-send; rolls back to pending if the write fails.
+- `POST /api/approvals/:id/dismiss` → remove without keystrokes.
+- `POST /api/approvals/session/:sessionId/viewed` → acknowledge the session's pending **idle** item (`acknowledgedAt`, emitted as `approval:updated`). Added after the owner reported that a yellow tab clicked and checked went yellow again on reload: the view-clears-idle rule lived in one browser's memory, so the seed re-armed it and other devices never saw the clear. Acknowledgement is deliberately **not** resolution (the prompt is still unanswered, so it stays in the inbox and stays available as Read My Mind context), and deliberately **idle-only** (looking at a permission/question dialog does not answer it, so the red alert survives being viewed).
+
+### SSE
+
+`approval:pending`, `approval:updated`, `approval:resolved` in `sse-events.ts` + `SSE_EVENTS` in constants.js (the parity test pins the sync). Broadcasts carry `sessionId`, so multi-user SSE scoping applies unchanged.
+
+### Push
+
+- `sendPushNotifications` payload gains `approvalId` for the three hook events. Both `approvalId` and the Approve/Deny `actions` are **gated on the opt-in setting**: with it off, permission pushes carry no buttons at all (pre-inbox they rendered and did nothing, so stripping them is the honest shape).
+- `sw.js` `notificationclick`: when `event.action` is `approve`/`deny`, POST `/api/approvals/:id/answer` directly from the worker (same-origin, cookie credentials) so the buttons work **with no tab open**; on failure fall back to focusing/opening a tab. Non-action clicks keep today's behavior.
+- Page-side `notification-click` handler: honor `action` instead of dropping it (also setting-gated, for stale notifications sent before the toggle flipped).
+- Question/idle pushes keep no action buttons (options vary per dialog); tapping opens the inbox.
+
+## Frontend
+
+New module `approvals-ui.js` (@loadorder 11.2, after panels-ui.js), prettier-formatted (not added to `.prettierignore`).
+
+- **Seed on connect**: `GET /api/approvals` on init and SSE reconnect; each pending item re-feeds `setPendingHook(...)` so tab alerts and the phone overview survive reload (fixes problem 2 with zero changes to the alert state machine). Items carrying `acknowledgedAt` are skipped, and `markIdleAlertSeen()` (app.js) is what sets it: viewing a session clears its yellow locally and POSTs `.../viewed`, so "I checked it" survives the reload and reaches the user's other devices through `approval:updated`.
+- **Desktop**: header bell `btn-approvals` with count badge. Ships default-hidden via marker class `btn-approvals--hidden` (same policy as the attachments button, so `test/mobile-header-buttons-policy.test.ts` excludes it from the default-visible enumeration); JS shows it only while count > 0. Click toggles a drawer of cards: session name + kind, tool/message summary, mono context block, buttons rendered from parsed options (else Approve/Deny), plus Dismiss and Open session. Esc closes; existing z-index layers respected.
+- **Phone**: header button stays hidden (`mobile.css`); the phone surface is the overview's NEEDS YOU section, whose rows gain inline ✓/✗ buttons for permission items (tap-through to the session remains the row's main action). Toolbar classes/status language rules from the mobile-overview section of CLAUDE.md apply.
+- **i18n**: new strings registered in i18n.js (en + zh-CN); status words carry `data-i18n-skip` where they would collide (mirroring the overview pills).
+- **Setting**: `approvalsInboxEnabled`, synced (in `SettingsUpdateSchema`), **default OFF** (owner decision: the entire feature is opt-in, meaning no bell, no drawer, no overview strips, no seeding, and no push action buttons until enabled in App Settings → Panels). Only the store and answer endpoints keep running regardless, so flipping the toggle ON surfaces anything already pending immediately, with no restart.
+
+## Race honesty
+
+The prompt can be answered in the terminal a moment before an inbox answer lands; then the keystroke would hit whatever now has focus (worst case: a digit typed into the composer, not submitted, since no `\r` is ever sent for menu answers). Mitigations, in order: answer-time re-capture (the dialog must still parse on screen or the answer is refused), answered-before-write marking, digit-only/Esc-only writes for menus, and the card's context block showing what the pane looked like when captured. This is the same class of risk `writeViaMux` automation (auto-resume, respawn) already accepts.
+
+## Tests
+
+- `test/approval-inbox.test.ts`: supersede per session, every resolution path, TTL, option parsing fixtures (2-option, 3-option with ❯, unparseable frame), re-capture update.
+- `test/routes/approval-routes.test.ts` (`app.inject`, no port): list; hook event creates item; answer approve/deny/option writes the exact bytes (test-PTY echo asserts them); text answers restricted to idle; 404 unknown id; 409 answered twice; option out of range rejected; multi-user scoping.
+- Existing suites extended: hook-event schema accepts the two new events; `sanitizeHookData` forwards bounded `message`; SSE parity + mobile-header policy pass as-is by construction.
+
+## Docs
+
+- CLAUDE.md: Key Patterns entry + SSE/route counts + frontend load order.
+- `docs/api-reference.md`: the two endpoints + three SSE events (additive, fine under the 0.9.x contract).

docs/browser-testing-guide.md

@@ -300,6 +300,11 @@ For reference when writing browser tests:
 .xterm                   // Terminal container
 #helpModal               // Help modal
 #appSettingsModal        // Settings modal
+#sessionOptionsModal     // Session Options (same set-* surface)
+#createCaseModal         // Add Case (same set-* surface)
+.set-rail-item           // Rail entry: scrolls in App Settings, switches in the other two
+.set-section             // A settings section (`.hidden` on the inactive ones outside App Settings)
+.set-row                 // One setting: label + description left, control right
 .modal-content           // Modal content
 .modal-close             // Modal close button
 .header-brand .logo      // Logo text

docs/claude-code-hooks-reference.md

@@ -149,9 +149,17 @@ to Claude as a system reminder. This implies `"async": true`; ordinary async
 hooks do not wake an idle turn, and their output waits for the next interaction.
 
 Codeman uses this on `PostToolUse(Bash)`: a self-contained Node helper extracts
-the background task ID from the Bash result, watches the session transcript for
-the matching completion notification, and exits 2. It does not send terminal
-input, so it cannot submit a user's partially written prompt.
+the background task ID from the Bash result, watches the originating transcript
+and, for subagents, the top-level parent transcript for the matching completion
+notification, and exits 2. Claude records a subagent's Bash result in its
+`subagents/agent-*.jsonl` file but queues completion in the lead session JSONL.
+The task ID keeps each wake targeted. The helper does not send terminal input,
+so it cannot submit a user's partially written prompt.
+
+For script-dispatched Codex work, `codex-run.sh` writes the final response
+between `CODEMAN_RESULT_BEGIN/END` markers in the background task output. The
+rewake helper includes a maximum of 64 KiB of that report in its feedback. UI
+subagent discovery and dispatcher result delivery are separate contracts.
 
 ### Notification
 
@@ -219,6 +227,16 @@ Or to allow exit:
 
 **Use Cases**: Control nested loops, verify subagent output.
 
+The hook input includes `agent_id`, `agent_transcript_path`, and
+`last_assistant_message`. Like `Stop`, a command hook can return
+`{"decision":"block","reason":"..."}` to keep the subagent running and feed
+the reason back to it.
+
+Codeman uses this to prevent premature reports from workers that still own live
+Monitor or background-Bash processes. It derives candidate task IDs from the
+subagent transcript, but requires a matching live Linux process descriptor for
+`tasks/<id>.output`; historical task text by itself is not treated as active.
+
 ### TeammateIdle
 
 **When**: When an agent-team teammate is about to go idle.

docs/claude-voice-plan.md

@@ -0,0 +1,121 @@
+# Claude voice dictation in Codeman
+
+Wire Codeman's existing mic button to the same speech-to-text service Claude Code's own
+`/voice` mode uses, so dictation works with **no third-party API key** for anyone already
+signed in to Claude Code on the server.
+
+## Why the CLI's own voice mode cannot be reused directly
+
+Claude Code 2.1.x ships voice input: `/voice hold|tap|off` arms it, the CLI opens the
+**host's** microphone (native `audio-capture-napi`, falling back to `sox`/`arecord` on Linux
+after probing `/proc/asound/cards`), streams PCM upstream and types the transcript into its
+own composer.
+
+Every part of that is on the wrong machine for Codeman. The CLI runs inside a tmux pane on
+the server, which is typically headless and has no sound card at all, while the human is in
+a browser on a phone somewhere else. Toggling `/voice` in the pane from Codeman would arm a
+microphone nobody is sitting in front of. So Codeman keeps capturing audio in the browser,
+where the user actually is, and only borrows the CLI's **transcription backend**.
+
+## The backend, as the CLI uses it
+
+Extracted from the 2.1.226 binary (`connectVoiceStream`):
+
+| | |
+| --- | --- |
+| URL | `wss://api.anthropic.com/api/ws/speech_to_text/voice_stream` |
+| Query | `encoding=linear16`, `sample_rate=16000`, `channels=1`, `endpointing_ms=300`, `utterance_end_ms=1000`, `language=<lang>`, `use_conversation_engine=true`, `stt_provider=deepgram-nova3` |
+| Headers | `Authorization: Bearer <Claude Code OAuth access token>`, `User-Agent`, `x-app: cli`, `anthropic-client-platform`, optional `x-config-keyterms` |
+| Audio | raw binary frames, PCM signed 16-bit little-endian, 16 kHz, mono |
+| Keepalive | `{"type":"KeepAlive"}` on open, then every 8 s |
+| Finalize | `{"type":"CloseStream"}`, then wait for the endpoint frame |
+| Downstream | `{"type":"TranscriptText"\|"TranscriptInterim","data":"…"}` (running interim), `{"type":"TranscriptEndpoint"}` (promotes the pending interim to final), `{"type":"TranscriptError",…}`, `{"type":"error","message":…}` |
+
+Deepgram Nova-3 runs server-side, so the Deepgram-quality result arrives without a Deepgram
+account. Verified against the live endpoint before this design was written: connect, stream
+PCM, receive interims and an endpoint frame.
+
+## Architecture
+
+The browser cannot call that endpoint itself: it would need the OAuth bearer token in page
+JavaScript (and CORS would refuse anyway). So the audio goes browser → Codeman → Anthropic,
+and Codeman is the only thing that ever touches the token.
+
+```
+mic → AudioWorklet (Float32 → PCM16 @16 kHz)
+    → wss://<codeman>/ws/voice/stream          [cookie/basic auth, Origin+Host guarded]
+    → VoiceStreamRelay (reads ~/.claude/.credentials.json per connect)
+    → wss://api.anthropic.com/api/ws/speech_to_text/voice_stream
+    ← {"t":"transcript","text":…,"final":…}    → existing _insertText() path
+```
+
+Nothing about the insert path changes: the transcript lands in the same preview overlay,
+the same direct/compose insert modes, the same green Send button.
+
+### Server pieces
+
+- **`src/claude-credentials.ts`** — locate and parse the Claude Code OAuth credentials.
+  `parseClaudeCredentials()` is pure (JSON string + `now` → status) and unit-tested;
+  `readClaudeOAuthToken()` wraps it with IO: `$CLAUDE_CONFIG_DIR/.credentials.json` or
+  `~/.claude/.credentials.json`, and on macOS the login keychain
+  (`security find-generic-password -s "Claude Code-credentials"`).
+  **Read-only, always.** Codeman never writes credentials and never refreshes the token: a
+  refresh rotates the refresh token, and racing Claude Code's own refresh could sign the
+  user out of their CLI. An expired token surfaces as a plain "run a Claude session to
+  refresh" error instead.
+  The token is never logged, never returned by any endpoint, and never sent to the browser.
+
+- **`src/web/voice-stream.ts`** — pure `buildVoiceStreamUrl()` / `buildVoiceStreamHeaders()` /
+  `sanitizeKeyterms()` (ASCII-only, deduped, 1024-char cap, mirroring the CLI), plus
+  `VoiceStreamRelay`, which owns one upstream socket: keepalive timer, audio passthrough,
+  transcript translation, finalize, and the caps below.
+
+- **`src/web/routes/voice-routes.ts`**
+  - `GET /api/voice/status` → `{ available, reason, subscriptionType?, expiresAt? }`. Never
+    the token. `available:false` with a machine-readable `reason` (`disabled`, `no-credentials`,
+    `expired`) is what the settings row and the provider resolver read.
+  - `GET /ws/voice/stream?language=&keyterms=` → the relay. Same upgrade guard as
+    `/ws/sessions/:id/terminal`: allowed Host, same-site Origin, and the global auth hook has
+    already run on the handshake.
+
+Caps, because an open mic is an open pipe: one stream per connection, `MAX_VOICE_STREAMS`
+concurrent server-wide, a hard `MAX_STREAM_MS` per stream, and a per-frame size cap. A tab
+left recording cannot bill an unbounded amount of upstream audio.
+
+### Frontend pieces
+
+- **`voice-pcm-worklet.js`** — an `AudioWorkletProcessor` converting Float32 blocks to PCM16
+  and posting ~256 ms frames back. `MediaRecorder` cannot produce raw PCM, which is why the
+  existing Deepgram path (container audio, auto-detected) cannot be reused as-is. Falls back
+  to `ScriptProcessorNode` where AudioWorklet is unavailable.
+- **`ClaudeVoiceProvider`** in `voice-input.js` — mirrors `DeepgramProvider`'s shape
+  (`start({language, keyterms, onStream, onResult, onError, onEnd})`) so `VoiceInput` treats
+  the three providers uniformly.
+- **Provider resolution** — new `voiceSettings.provider`: `auto` (default) | `claude` |
+  `deepgram` | `webspeech`. `auto` picks Claude when `/api/voice/status` reports it
+  available, else Deepgram when a key is set, else Web Speech. Pinning a provider always
+  wins, so an existing Deepgram user can keep exactly what they have.
+
+### Settings
+
+- `claudeVoiceEnabled` — synced, **default OFF**, gating the whole server side. Off is the
+  honest default: turning it on means this machine's Claude subscription starts paying for
+  transcription for whoever can reach the UI, and the audio goes to Anthropic rather than to
+  wherever it went before. One switch in Settings → Voice, and the mic works with no key.
+- `voiceSettings.provider` — per the resolution table above; joins the existing synced
+  `voiceSettings` object.
+
+## Things worth knowing
+
+- **This uses an undocumented endpoint with subscription credentials.** It is the user's own
+  token, on the user's own machine, driving the user's own Claude Code install, but it is not
+  a published API and Anthropic can change or restrict it. Default-OFF is deliberate; the
+  Deepgram and Web Speech paths stay untouched as the supported fallbacks.
+- **Multi-user mode**: every user's dictation would run on the server owner's Claude
+  credentials, exactly as every user's *sessions* already run on them. Consistent, but worth
+  stating out loud in the settings copy.
+- **Token lifetime** is about 8 hours, refreshed by Claude Code itself whenever it runs. The
+  relay re-reads the file on every connect rather than caching, so a refresh is picked up on
+  the next press of the mic.
+- **HTTPS or localhost**: `getUserMedia` needs a secure context. Prod is HTTPS behind
+  `tailscale serve`, so this is already satisfied; the existing error copy covers the rest.

docs/cli-enable-disable-plan.md

@@ -0,0 +1,314 @@
+# CLI management Settings UI + write API — plan
+
+> Tracked separately from `DEPLOYMENT_PLAN.md` (PR B2, merged) and `docs/copilot-integration-plan.md`
+> (parked). This is "PR C" from the original #343 review: *"settings UI + write endpoints +
+> auto-install, once we've settled the trust model... I want to make that call on its own, not
+> inside a 100-file diff."*
+>
+> **Phase 0 is CLOSED as of 2026-09-21** — all three original pieces are IN SCOPE (expanded from
+> this plan's first draft, which recommended #2/#3 as separate/out-of-scope; the user chose full
+> scope instead, with the risk called out explicitly for #3 before confirming). See "Decisions"
+> below for the full record.
+
+## Status as of 2026-09-22
+
+**Phases 1–6 are ALL IMPLEMENTED** (commits `da07b38c` "add cliManagementEnabled flag and GET
+/api/clis" and `db4557d9` "Phases 3-6 - write API + custom entries + Settings UI", both on this
+branch, `feat/cli-management`). Confirmed present in the tree: `cliManagementEnabled` in
+`SettingsUpdateSchema`; `GET /api/clis`, `PUT /api/clis/:id`, `POST /api/clis/:id/install`,
+`POST /api/clis`, `PUT /api/clis/custom/:id`, `DELETE /api/clis/:id` in
+`src/web/routes/cli-registry-routes.ts`; the `shell`/`claude` `UNDISABLEABLE_IDS` backend guard;
+`isAdmin(req)` gating on both the list and write routes; `appendAdminAudit` wired into the install
+route; tmp+rename+`0o600` writes in `registry-writer.ts`; the full Settings UI (row list, toggle,
+Install button, custom-entry create/edit/delete form) in `settings-ui.js` + `index.html`.
+`test/routes/cli-registry-routes.test.ts` (425 lines) and `test/cli-registry-no-id-branching.test.ts`
+cover it. This status section, plus the fix and gap below, is the one piece of that work done in
+a *different* session from the one that wrote Phases 1–6 — reviewed by reading the diff and
+verifying each claim against the actual routes/tests, not by re-implementing anything.
+
+### Gotcha found and fixed (commit `0c77dd0a`)
+
+**Toggling a CLI off in Settings had no effect anywhere except the Settings row itself.**
+`window.__codemanCliAvailable` — the flag `isCliAvailable()` reads client-side to gate the
+welcome-screen buttons, the Run-menu dropdown and the mobile overview — is injected **once**, at
+initial page render (`server.ts`), built purely from each CLI's own installed-on-PATH resolver
+(`isClaudeAvailable()` etc.), with **no reference to the registry's `enabled` flag at all**. So
+disabling a CLI here updated its own row and nothing else — every launch surface kept offering it,
+both live and after a full page reload, since even a *fresh* render never consulted the registry.
+Root-caused and reported by the user testing the live feature ("toggle those off, they still
+appear in that menu and on the front main screen").
+
+Fixed two places:
+- `server.ts`: after building `available`, intersect the nine real `SessionMode` ids against
+  `enabledClis()`. `git`/`cloudflared` (utility binaries, not CLI registry entries) and
+  `deepseekBinary` (a secondary installed-only flag for the "add a profile" affordance) are
+  deliberately left alone — they were never registry-gated to begin with.
+- `settings-ui.js`: `toggleCliEnabled()` now patches `window.__codemanCliAvailable` in place and
+  refreshes the welcome screen, the mobile overview and an already-open Run menu, mirroring the
+  existing `installDeepSeekProfile()` pattern for the same "injected once, needs an explicit
+  patch" reason — the server-side fix alone still left every surface stale until the next reload.
+
+New test in `test/render-index-html.test.ts`: an installed-but-disabled CLI (codex, forced via
+`clis.json` + `reloadCliRegistry()`) reads as unavailable, while an installed-and-enabled one
+(claude) is unaffected by the override.
+
+**Verified on the Debian devbox** (`codeman-devbox`, real tmux — this sandbox has none and
+`WebServer`'s constructor hard-requires it): typecheck clean, the new test passes (17/17 in
+`render-index-html.test.ts`), the CLI-registry suites pass (86/86), and the **full CI gate is
+green — 415 test files, 7855 tests, 0 failures**.
+
+### Launch-surface registry integration — completed
+
+The welcome screen, desktop Run menu and mobile Run picker now use the same injected CLI catalog.
+Every enabled registry entry is rendered; unavailable binaries remain hidden as before. Settings
+updates the catalog and availability flags in place after enable/disable, create, edit or delete,
+so the launch surfaces update without a page reload. A custom entry uses the generic quick-start
+path, while stock entries retain their existing per-CLI launch settings.
+
+Not otherwise re-verified line-by-line against every Phase 1–6 checklist item below (e.g. the
+exact wording of toasts, the "same PR" sequencing notes) — the checklists are left as originally
+written; treat the **Status** section above as authoritative for what exists.
+
+---
+
+## Background
+
+`src/config/cli-registry/registry.ts` is READ-ONLY today, and says so in its own header comment:
+
+> "⚠️ READ-ONLY. Nothing in this module writes, creates or migrates the file... there is no
+> settings UI and no write API yet... A `seededStockIds` ratchet belongs with the write API that
+> needs it."
+
+Confirmed on `master` (2026-09-21): no `/api/clis` route exists at all (read or write);
+`~/.codeman/clis.json` is hand-edit-only; `resolveInstallCommandForPlatform()` is documented
+"Display text only — never executed" — nothing runs an install command server-side today. The
+original #343 review flagged the opposite (`spawn(command, {shell: true})`, `env.allowedPrefixes`
+contributed from a write) as needing its own trust-model decision; that decision was never made
+after the split, just dropped. This plan makes it.
+
+**Closest existing precedent, and the template this plan follows for the read/write API**:
+`src/web/routes/custom-model-routes.ts` + `src/custom-model-hosts.ts` (#393/#430/#459) — a small
+per-item JSON store, Settings-UI-driven, admin-gated in multi-user mode, tmp+rename+0600 writes.
+
+**Precedent for the new master feature flag (Phase 1)**: `customModelEndpointsEnabled` —
+`z.boolean().optional()` in `SettingsUpdateSchema` (`schemas.ts:1319`), a checkbox read/written by
+id in `openAppSettings()`/`saveAppSettings()` (`settings-ui.js:401`/`:2120`). SYNCED, not
+per-device (present in the schema, absent from `displayKeys`), default OFF.
+
+**Spec refs for the whole plan:**
+- `src/config/cli-registry/registry.ts` — the read path; `resolveRegistry()`'s merge semantics
+  (`deepMerge`, `UNMERGEABLE_KEYS`) apply unchanged to whatever this plan writes
+- `docs/cli-registry.md` — registry shape, "The override file", "Arg-template safety" (the four
+  layers Phase 5's custom-entry validation must not weaken), "Adding a CLI" (the 5-step recipe a
+  custom entry does NOT get to skip just because it arrives via UI instead of a stock.ts edit)
+- `src/web/routes/custom-model-routes.ts` + `src/custom-model-hosts.ts` — read/write API template
+- `docs/multi-user-plan.md`, `docs/security-architecture.md` — admin-gating conventions
+- `CLAUDE.md` §Multi-user mode, §"Settings surface", §"Per-device vs synced settings"
+
+---
+
+## Decisions (Phase 0, closed 2026-09-21)
+
+1. **Enable/disable a stock CLI's `enabled` flag** — IN SCOPE. Plus a **master feature flag**
+   (`cliManagementEnabled`, synced, default OFF) gating the whole Settings UI section's visibility,
+   matching this codebase's standing convention for new admin-facing surfaces.
+2. **Auto-install** (stock CLIs' already-shipped, already-vetted install commands) — IN SCOPE,
+   same PR.
+3. **Custom CLI entries via the UI** — IN SCOPE, **typed-argv only**: a custom entry goes through
+   the exact same schema/argv-safety path stock entries do (named token patterns, no raw shell-text
+   field). Its install command stays **display-only text**, same as every stock entry today — Phase
+   4's auto-install NEVER executes a custom entry's install command, only a stock one's. This is
+   the one place scope was deliberately narrowed relative to what was agreed in principle, because
+   `docs/cli-registry.md`'s arg-template-safety section exists specifically to keep config free of
+   shell text, and a free-text install command for a user-defined entry would reopen exactly that.
+4. **`shell`/`claude` un-disableable** — enforced at the **backend**, not just the UI (a
+   frontend-only guard is bypassable with curl).
+5. **Non-admin visibility in multi-user mode** — the CLI-management Settings section is **hidden
+   entirely** for a non-admin, not shown-empty.
+6. **`seededStockIds` ratchet** — not needed. `deepMerge()` only overrides a key the file actually
+   sets, so a CLI absent from `clis.json.clis` always falls through to its stock `enabled` value
+   with no special-casing. (Carried over from the first draft, not re-litigated.)
+
+---
+
+## Phase 1 — Master feature flag: `cliManagementEnabled`
+
+**Status:** DONE (commit `da07b38c`) — verified present in `SettingsUpdateSchema`, `index.html`,
+`openAppSettings()`/`saveAppSettings()`.
+
+**Spec refs:**
+- `schemas.ts:1319` (`customModelEndpointsEnabled`) — the exact pattern to mirror: `z.boolean().optional()`
+  in `SettingsUpdateSchema`
+- `settings-ui.js:401`/`:2120` — checkbox read/write by id in `openAppSettings()`/`saveAppSettings()`
+- `CLAUDE.md` §"Adding Features" → "App setting" — decide per-device vs synced FIRST (this one is
+  synced: a feature toggle, not a display preference) and add to `displayKeys` NEVER for a synced
+  setting
+
+**Checklist:**
+- [x] Add `cliManagementEnabled: z.boolean().optional()` to `SettingsUpdateSchema`
+- [x] Add the checkbox to `index.html`'s `#settings-clis` section, above where Phase 6's per-CLI
+      list will render — reads/writes via `openAppSettings()`/`saveAppSettings()` by id, same as
+      `customModelEndpointsEnabled`
+- [x] `readCliManagementEnabled()` helper (mirrors `readCustomModelEndpointsEnabled()` in
+      `custom-model-routes.ts:609`) for the route file(s) in Phases 2-5 to gate on
+- [x] When OFF: `GET /api/clis` still exists but the Settings UI section stays hidden
+      (`applyCliManagementVisibility()`); the write endpoints reject (see Phase 3)
+
+**Verify:** `npm run typecheck` passes; a unit test confirms `SettingsUpdateSchema` accepts/rejects
+the field correctly; toggling it in a fresh browser profile shows/hides the Settings section with
+no server restart.
+
+---
+
+## Phase 2 — Read endpoint: `GET /api/clis`
+
+**Status:** DONE (commit `da07b38c`) — verified present in `src/web/routes/cli-registry-routes.ts`.
+
+**Spec refs:**
+- `src/web/routes/custom-model-routes.ts:730` (`GET /api/model-endpoints`) — multi-user read
+  gating: empty list for a non-admin, never a 403
+- `src/config/cli-registry/registry.ts` — `listClis()` (every entry, including disabled stock
+  ones — this is an admin/settings surface, unlike `enabledClis()`)
+- `window.__codemanCliAvailable`'s resolvers (`isClaudeAvailable()` etc.) — candidate `installed`
+  source; confirm whether to reuse directly or the response needs its own probe (Open Question 4,
+  carried from the first draft — still genuinely open, decide during this phase not before)
+
+**Checklist:**
+- [x] New route file `cli-registry-routes.ts`
+- [x] Response excludes `launch`/`env`/`capabilities`/`overlays`/`discovery`
+- [x] `isMultiUserMode() && !isAdmin(req)` → `[]`
+- [x] Unit tests in `test/routes/cli-registry-routes.test.ts` (admin/non-admin/single-user,
+      disabled stock CLI still present)
+
+**Verify:** `npm test -- test/routes/cli-registry-routes.test.ts` passes; `curl localhost:3000/api/clis | jq`
+shows every stock CLI including disabled ones.
+
+---
+
+## Phase 3 — Write endpoint: `PUT /api/clis/:id` (stock enable/disable)
+
+**Status:** DONE (commit `db4557d9`) — `UNDISABLEABLE_IDS`, admin gate, tmp+rename+0600 all
+confirmed present.
+
+**Spec refs:**
+- `src/web/routes/custom-model-routes.ts:753` + `src/custom-model-hosts.ts:91` — write-path
+  template: `adminOnly` gate, read-modify-write the WHOLE file, tmp+rename+0600
+- `registry.ts:47` (`filePath()` = `dataPath(...)`) and `reloadCliRegistry()` — write to the same
+  resolved path, invalidate the cache on every successful write or the change is invisible until
+  restart
+
+**Checklist:**
+- [x] Body: `{ enabled: boolean }`. Zod schema in `schemas.ts`
+- [x] Gate order: `cliManagementEnabled` → `adminOnly` → shell/claude guard → stock-only guard
+- [x] Rejects disabling `shell` or `claude` (`UNDISABLEABLE_IDS`)
+- [x] Rejects a write for an id that isn't a stock CLI
+- [x] Deep-merges `{ clis: { [id]: { enabled } } }`, preserving other override keys
+- [x] tmp+rename+0600 write, `reloadCliRegistry()` on success
+- [x] Unit tests (`test/routes/cli-registry-routes.test.ts`)
+
+**Verify:** `npm test` full gate green; `curl -X PUT localhost:3000/api/clis/grok -d '{"enabled":false}'`
+then `GET /api/clis` shows the change with no restart; same against `shell`/`claude` returns an
+error and changes nothing; `ls -la ~/.codeman/clis.json` shows mode 0600.
+
+---
+
+## Phase 4 — Auto-install: `POST /api/clis/:id/install` (stock CLIs only)
+
+**Status:** DONE (commit `db4557d9`) — route present, `appendAdminAudit` wired in.
+
+**Spec refs:**
+- `registry.ts:231` (`resolveInstallCommandForPlatform`) — currently "Display text only — never
+  executed"; this phase is what changes that, for stock entries only, with Decision 2's sign-off
+- Original #343 review's exact concern re: `env.allowedPrefixes` contributed from a write — stays
+  out of scope; this phase only ever runs a command, never touches the env allowlist
+
+**Checklist:**
+- [x] Separate endpoint from Phase 3's toggle
+- [x] Gate order: `cliManagementEnabled` → `adminOnly` → stock-entry-only guard
+- [x] `resolveInstallCommandForPlatform(entry)` for the target
+- [x] Bounded execution (timeout, captured stdout/stderr)
+- [x] Does NOT auto-enable on successful install
+- [x] Audit-logged via `appendAdminAudit`
+- [x] Unit tests
+
+**Verify:** a real install triggered via the endpoint against a CLI not currently installed,
+`GET /api/clis`'s `installed` field flips true with no restart; audit log entry present; attempting
+install against a custom entry's id fails with a clear error; full CI gate green.
+
+---
+
+## Phase 5 — Custom CLI entries: create / update / delete via API
+
+**Status:** DONE (commit `db4557d9`) — `POST /api/clis`, `PUT /api/clis/custom/:id`,
+`DELETE /api/clis/:id` all present. Open Question 2 resolved: a **separate** endpoint
+(`PUT /api/clis/custom/:id`), not Phase 3's `PUT /api/clis/:id` widened.
+
+**Spec refs:**
+- `docs/cli-registry.md` §"Arg-template safety" (all four layers), §"Adding a CLI" (the 5-step
+  recipe) — a custom entry created via this API must satisfy the SAME schema (`CliEntrySchema`)
+  every stock entry does; there is no relaxed path for UI-originated entries
+- `registry.ts`'s `resolveRegistry()` — the custom-entry branch (`stock: false`, dropped with a
+  warning on validation failure, never falls back silently) already exists and is unchanged by
+  this phase; this phase only adds a way to WRITE what that branch reads
+
+**Checklist:**
+- [x] `POST /api/clis` (create), full `CliEntrySchema` validation
+- [x] `PUT /api/clis/custom/:id` (update) — separate endpoint from Phase 3's stock toggle
+- [x] `DELETE /api/clis/:id` refuses for any stock id
+- [x] `id` collision check against existing stock ids
+- [x] `discovery.install.command` on a custom entry stays DISPLAY-ONLY
+- [x] Same tmp+rename+0600 write pattern, `reloadCliRegistry()` on every successful mutation
+- [x] Unit tests
+
+**Verify:** `npm test` full gate green; create a custom entry via curl, confirm it appears in
+`GET /api/clis` — **confirm it appears in the Run menu is UNVERIFIED and currently FALSE, see
+"Outstanding" above**; delete it, confirm it's gone and `clis.json` no longer references it.
+
+---
+
+## Phase 6 — Settings UI
+
+**Status:** DONE (commit `db4557d9`) — `#cliListGroup`, row rendering, toggle, Install button,
+custom-entry create/edit/delete form all present in `settings-ui.js`/`index.html`. Manual browser
+verification per the phase's own "Verify" step (flag on/off, non-admin hidden, toggle stops the
+Run menu offering a CLI, create/enable/launch a custom entry, delete it, shell/claude undisableable)
+has **not** been re-run in this session — the toggle→Run-menu leg specifically was BROKEN until the
+gotcha fix above, and the create→launch leg for a custom entry is the confirmed gap in
+"Outstanding".
+
+**Spec refs:**
+- `index.html:2357` (`#settings-clis`) — the existing home; Phase 1's master toggle at the top,
+  then the per-CLI list, then (if `cliManagementEnabled`) a "custom CLI" creation form, all above
+  the existing Codex-only groups
+- `CLAUDE.md` §"Settings surface" — App Settings scrolls, it does not tab-switch
+- `admin-ui.js` — pattern for an admin-only-VISIBLE section (not just admin-only-writable),
+  needed here per Decision 5
+
+**Checklist:**
+- [x] Whole section hidden when `cliManagementEnabled` is OFF, and separately hidden for a
+      non-admin in multi-user mode (`_applyCliManagementAdminGate`)
+- [x] Fetches `GET /api/clis` when the section becomes visible; renders one row per CLI
+- [x] Stock rows: enabled toggle only; `shell`/`claude` rows show the toggle disabled/greyed
+- [x] Custom rows: enabled toggle plus edit/delete affordances
+- [x] "Add custom CLI" form (id/label/badge/binary/argv)
+- [x] Toggle/edit/delete update the row in place
+
+**Verify:** manual browser test per `CLAUDE.md`'s "Always Test Before Deploying" rule — **not yet
+re-run end-to-end in this session**; do this before considering the feature ready to ship, and
+expect the custom-entry-launch step to fail until the Outstanding gap above is closed.
+
+---
+
+## Remaining Open Questions
+
+1. **Phase 2's `installed` source** — resolved: reuses `window.__codemanCliAvailable`'s existing
+   resolvers via `GET /api/clis`'s own probe (confirmed by reading the route).
+2. **Phase 5's `PUT` endpoint shape** — resolved: a **separate** endpoint
+   (`PUT /api/clis/custom/:id`), not Phase 3's toggle route widened.
+3. **Sequencing against the parked Copilot plan** — unchanged, still not blocking.
+4. **NEW: custom-CLI Run-menu integration** — see "Outstanding" above. Not decided or started.
+
+---
+
+Implementation is underway (see Status above); this line is left for history rather than removed —
+the plan was originally approved before Phases 1–6 landed.

docs/cli-registry.md

@@ -0,0 +1,256 @@
+# The CLI registry
+
+Every run mode Codeman can launch — Claude Code, Terminal/Shell, OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek Harness and OMP — is a `CliEntry`: a data record describing how to find the binary, how to build its command line, what environment it needs, and what it can do. Code that used to ask "which CLI is this?" asks the entry instead.
+
+## Where it lives
+
+| File | What it holds |
+| ------------- | ------------------------------------------------------------------------------------------------- |
+| `types.ts` | The `CliEntry` interface and everything under it. Read this first. |
+| `stock.ts` | The shipped catalog. **The only file allowed to name a CLI id.** |
+| `schema.ts` | Zod validation, including the cross-field checks that reject an incoherent entry at LOAD time. |
+| `argv.ts` | The argv engine: the only code that turns typed tokens into a command string. |
+| `patterns.ts` | The NAMED value patterns (`model`, `uuid`, `path-segment`, …) and the regex-compilation guard. |
+| `profiles.ts` | The names of behaviours that genuinely need code, kept import-free so `schema.ts` can validate one. |
+| `registry.ts` | Loading, merging `~/.codeman/clis.json`, and the accessors (`getCli`, `enabledClis`). |
+
+`src/session-cli-registry-bridge.ts` maps the legacy per-mode option bag onto the engine, and `src/utils/cli-resolver.ts` / `src/utils/cli-launcher.ts` do registry-driven binary resolution and launcher-profile dispatch.
+
+## The override file
+
+`~/.codeman/clis.json` (instance-scoped through `dataPath()`) holds overrides and custom entries only, never a copy of the stock catalog: `{ "clis": { "<id>": { ...partial entry... } } }`. Objects merge key-wise onto the stock entry, arrays replace wholesale. **The file must be mode 0600**; the loader refuses any group/world permission bit, read bits included, so a file created with a normal umask (0644) is ignored until you `chmod 600` it. Every reason a file was ignored or an entry dropped is logged once, prefixed `[cli-registry]`, on the first load. A stock entry whose override fails validation falls back to the shipped definition; a custom entry that fails is dropped. The file is read once per process and re-read after a change made through CLI management (below).
+
+## Managing CLIs from Settings
+
+App Settings → Agents & CLIs → **CLI management** (`cliManagementEnabled`, default OFF; admin-only in multi-user mode) lists every entry with an installed/not-installed badge and:
+
+- toggles any entry on or off. A `kind: 'shell'` entry cannot be disabled, and the row shows no switch for it. A disabled CLI disappears from the Run menu, the welcome screen and the phone overview, and new session requests for it are rejected.
+- installs a missing **stock** CLI by running its shipped install command, after a confirm that names the exact command. Only one install per CLI runs at a time, and the command runs without any `CODEMAN_*` variable in its environment. A custom entry's install command is never executed.
+- adds, edits and deletes **custom** entries (id, label, badge, binaries, launch argv). The server re-validates the whole assembled entry through `CliEntrySchema`, so the form cannot bypass the load-time rules.
+
+These are the only writes to `clis.json`. They are serialized, and a file that does not parse or has unsafe permissions is refused rather than overwritten; fix it (or `chmod 600` it) and retry. The HTTP routes are listed in `docs/api-reference.md` under *CLI management*.
+
+## The shape of an entry
+
+```ts
+interface CliEntry {
+  id: CliId; // 'codex'
+  label: string; // 'Codex' — shown in menus
+  shortBadge: string; // tab badge, e.g. 'CX'
+  accent: string; // single hex colour
+  enabled: boolean;
+  stock: boolean; // set by the loader; a custom entry can never claim it
+  order: number;
+  kind: 'agent' | 'shell';
+  discovery: CliDiscovery; // how to find and prove the binary
+  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, watchingLine?, watchingLines?, awaitingLine? }
+  //   — how this CLI's pane shows work, work it started in the background, and a turn
+  //   that ended waiting for workers it will resume from
+  overlays: CliOverlays; // remote-SSH / Docker pane commands, credential store
+}
+```
+
+`capabilities` is the important part. It is what `isExternalCliMode()`, `isAltScreenStripMode()`, `hooksAvailableForMode()` and every other former per-mode branch actually read.
+
+### Regexes that come from config
+
+Four capability fields carry a regular expression an override file can set: `discovery.version.regex`, `capabilities.workDetect.workingLine`, `capabilities.workDetect.watchingLine` and `capabilities.workDetect.awaitingLine`. All four 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.
+Claude's Artifact comment monitor is the one chip that does not count. It waits for a human
+to comment on a page the agent published, so Claude's pattern refuses any footer that
+carries it, and the idle alert goes out as usual.
+
+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.
+
+`awaitingLine` covers the quiet pane that is neither idle nor watching: a turn that ENDED
+to wait for workers the CLI will resume from by itself. When background agents or an
+ultracode workflow are still running at turn end, Claude closes the turn with
+`✻ Waiting for 1 dynamic workflow to finish` instead of `✻ Brewed for 1m 18s`, and a pane
+showing that row counts as working. ⚠️ Claude renders the row once and never redraws it, so
+the words are still on screen after the workers report back and the follow-up turn ends.
+The pattern is therefore never run over the whole pane: `isAwaitingWorkers()`
+(`session-activity.ts`) walks up from the composer past blank, framed and indented rows and
+tests only the first row that starts in column 0, which is the newest transcript row. Claude
+starts its own rows in column 0 and the agent's prose never does, so the anchor also keeps an
+agent from holding its own session busy.
+
+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.
+
+`test/cli-capability-predicates.test.ts` asserts that no two of the three are equivalent across the catalog, so collapsing them fails the build rather than a user's session.
+
+## Arg-template safety
+
+The composed command line is interpolated into `bash -c "…"` inside tmux, which makes command construction a security boundary. Four independent layers keep config out of it:
+
+1. **Config contains no shell text.** There is no `command: "..."` field anywhere in the schema. An entry declares a sequence of typed tokens; `argv.ts` is the only place that turns them into a string, and it owns every separator itself — one space between tokens, ` || ` between fallback variants. Neither can originate from config, because config has no field that could hold either.
+2. **Every literal is validated at LOAD time** against a safe-word pattern (no space, quote, backtick, `$`, `;`, `&`, `|`, redirection, parens, braces, newline or backslash). A bad literal **rejects the whole entry** rather than being dropped, because a silently dropped flag would change security-relevant behaviour — losing `--no-approve` is not a cosmetic difference.
+3. **Values resolve through NAMED patterns.** A value placeholder selects a `TokenPattern` (`model`, `uuid`, `slug`, `path-segment`, `tool-list`, …) from `patterns.ts`; config can never supply its own regex for a value, so a `clis.json` structurally cannot widen its own validation. A value that fails its pattern drops the whole argument, exactly as the hand-written builders did: an invalid `--model` omits `--model`, it never substitutes something else.
+4. **Escaping is independent of validation.** `renderToken()` re-checks the resolved value before emitting it unquoted, and single-quotes anything else — so even a value that somehow bypassed validation is quoted, never concatenated raw.
+
+The only config-supplied regexes are `discovery.version.regex` and `discovery.identity.regex`. Both run against **command output** rather than a shell token, both are compiled through `compileVersionRegex()` (length cap, nested-quantifier rejection, never the `g` flag), and the output they see is truncated first.
+
+## Named profiles: the escape hatch
+
+Some differences genuinely need to run code rather than be described. Those are **named profiles**: a capability field holds a profile NAME, and the implementation lives in one place keyed by that name — never by CLI id.
+
+- `discovery.launcherProfile` — for a CLI whose binary is not the agent. `dsh` boots `$DSH_HOME/profiles/<name>`, so "installed" and "runnable" have different answers; the profile answers both, plus why a specifically-named target will not work. Implemented in `utils/cli-launcher.ts`.
+- `env.setenvProfile` — per-CLI environment setup that is more than a list of keys, such as DeepSeek's status bridge.
+- `capabilities.transcript` — which on-disk history reader understands this CLI (`claude-jsonl`, `codex-rollout`, `deepseek-zstd`, `omp-jsonl`, `none`).
+- `capabilities.echo.predictProfile` — the predictive-echo model a composer needs.
+
+The names live in `profiles.ts`, which is kept free of imports so `schema.ts` can validate a name at load time. A profile this build does not implement is a load-time error naming the field, rather than a CLI that silently looks permanently uninstalled.
+
+## DeepSeek: the four assumptions it breaks
+
+DeepSeek is worth reading before assuming an entry looks like its siblings — the schema carries four extensions because of it.
+
+| What it breaks | How the registry expresses it |
+| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `dsh` is a profile LAUNCHER, not the agent, so "installed" is not "runnable". | `discovery.launcherProfile` + `discovery.launcherTargetParam`. |
+| Its permission switch is the **`DSH_PERMISSION_MODE` env var**, not a flag — the harness has none. | `env.configSetenv` (so the ordinary `privilegedParams` clamp still reaches it) **and** `capabilities.privilegedEnvKeys`. |
+| It is the only non-claude mode with real hook signals, and for it that is a per-SESSION question. | `capabilities.hooks: 'supervised'` — a third state, not a boolean. |
+| Its transcript is zstd session files, one frame per write. | `capabilities.transcript: 'deepseek-zstd'`. |
+
+## Identity probes
+
+`discovery.identity` asks the binary whether it is the program we meant, and it runs **before** the version probe, because a version probe cannot tell an impostor from the real thing. Debian ships an unrelated `dsh` (dancer's shell) that answers `--version` perfectly happily, and npm carries squatters for both `pi` and `grok`.
+
+`discovery.version.requireVersionMatch` is the weaker companion: a binary whose version output has the wrong shape counts as ABSENT rather than present-with-unknown-version. That is what a short, generic binary name needs, and it is what keeps `codeman doctor` and the run mode from telling the user opposite things about the same binary — both read the same regex off the same entry.
+
+## The no-id-branching rule
+
+`test/cli-registry-no-id-branching.test.ts` fails the build if a CLI id comparison appears outside the stock catalog. It builds its id list from the live catalog, blanks comment lines before scanning (comments legitimately quote the pattern to explain why a branch was removed, and blanking rather than dropping is what keeps reported line numbers pointing at the real file), and keeps an allowlist in which **every entry carries its reason**.
+
+It matches four shapes, not one: `mode === '<id>'`, `mode !== '<id>'`, `case '<id>':`, and `['<id>', …].includes(mode)`. The first version matched `===` only, and that gap was not academic — the refactor it guards converted the `===` sites and left the negated ones, so 36 `!==` branches survived it, including a seven-mode chain auto-enabling Ralph under a comment asking the next person to keep it in step with a predicate by hand while the sibling code path already read the capability. A guard that sees half the shapes reports a count measured over the half it happens to catch.
+
+The allowlist is not a formality. If a branch is about what a CLI can DO it belongs in `CliCapabilities`; the entries that remain are things that are not CLI-behaviour branches at all — chiefly the legacy per-mode `<Mode>Config` objects on `POST /api/sessions`, which are a fact about the public HTTP API rather than about any CLI, plus a few documented cases where `mode === 'claude'` is genuinely the right question (Read My Mind reads Claude's _own_ transcript, so a capability there would be actively wrong).
+
+`test/frontend-cli-no-id-branching.test.ts` is the same guard for the two frontend files the CLI registry's Run-menu consolidation touches, `session-ui.js` and `mobile-overview.js` — deliberately not the rest of `src/web/public/`, whose per-CLI rules stay out of scope for now (see "Fields declared for later" below). Its allowlist keys on `<file>::<expression>` with no line number, since a single unrelated edit to a contended file would otherwise shift every subsequent line and make every entry go stale at once, and each entry additionally carries the exact number of approved call sites — a bare key would let a brand-new branch reusing an already-approved expression land unreviewed. Its comparison shape differs from the backend guard's in one respect: the left-hand side may be any identifier, not only one named `mode`, `id` or `agentType`, because the review of #458 found `const m = this._runMode; if (m === 'codex')` slipping past the named form while the scanned file already filters with `(m) => m !== 'shell'`.
+
+## Two namespaces called `param`
+
+`launch.params` keys, `env.configSetenv[].fromParam` and `capabilities.privilegedParams[].param` all name a **launch param**. The **legacy wire field** a param arrives as is a separate namespace, and `launch.legacyConfigAliases` is the only bridge between the two.
+
+This matters because it is invisible when it is wrong. `capabilities.privilegedParams[].param` is the multi-user bypass clamp's only handle on a CLI's privilege switch, and a name from the wrong namespace clamps **nothing**: no load error, no failing test, the clamp simply stops running. Codex is the entry where the two names differ (`bypassApprovals` as the param, `dangerouslyBypassApprovals` on the wire), so it is the one that catches a regression. `schema.ts` rejects any entry naming a param it never declared, on both `configSetenv.fromParam` and `privilegedParams.param`.
+
+## Fields declared for later
+
+`accent`, `capabilities.echo`, `capabilities.wheelForward`, `capabilities.keyboardAccessory` and `capabilities.maxFrameBytes` are **declared but not yet read**. (`shortBadge` was on this list until the CLI management list in Settings started showing it.) 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, 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.
+
+Everything else in the interface is live, including `overlays.remote` / `overlays.docker`, which back `defaultRemoteCommandForMode()` and `defaultDockerCommandForMode()` directly. Those two used to be hardcoded `Record<…CommandMode, string>` tables duplicating the registry with nothing keeping the two in step; `test/location-overlay-commands.test.ts` pins every resulting command as a literal string.
+
+## Consumers outside the server
+
+Two things need the catalogue but cannot import TypeScript, so `npm run generate:cli-catalog`
+(`scripts/generate-cli-catalog.mts`) emits two artifacts from `stock.ts`. Both are committed,
+and `test/cli-catalog-sync.test.ts` fails if either drifts from a fresh generation.
+
+| Artifact | Consumer | Why it exists |
+| ------------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------- |
+| `config/clis.stock.json` | `scripts/lib/cli-catalog.mjs` (Docker build args), tests | A `.mjs` cannot import the registry. |
+| a marked block inside `install.sh` | the installer itself | It runs via `curl \| bash` before any checkout exists, so it can read neither. |
+
+Only `id`, `label`, `shortBadge`, `enabled`, `order`, `kind` and `discovery` are exported.
+`launch`, `env`, `capabilities` and `overlays` are spawn-time concerns the server alone
+interprets, and a test asserts they never leak into the artifact — a second reading of the
+launch model in a consumer that cannot be tested against a real spawn is exactly what this
+registry exists to prevent.
+
+The install.sh copy is **embedded, not fetched**, and is the FULL catalogue. An earlier design
+fetched it and fell back to a hardcoded two-CLI list, which degraded silently on an empty
+response; there is no degraded mode to fall into now, and no network fetch either — a `curl |
+bash` from master already carries a catalogue exactly as fresh as the script itself, so there is
+nothing a refresh would buy that isn't already true. An earlier draft added an opt-in refresh
+with a `TRUSTED`/`DISPLAY` array split to keep it from ever writing the executed command; it was
+dropped before merge rather than shipped half-verified — the split's only actual write was the
+label, `DISPLAY` never diverged from `TRUSTED` in practice, and the added surface (a second
+array, a fetch path, three failure shapes to warn on) bought nothing the embedded copy didn't
+already have.
+
+### The install-command trust boundary
+
+Three rules, and the middle one is why the embed matters:
+
+1. **The server never executes an entry's `install.command`.** Unchanged, and still enforced by nothing executing it: the field is display text (`CliDiscovery.install.command`).
+2. **`install.sh` executes only commands embedded in itself.** Those arrive in the same file, over the same TLS fetch, in the same commit as the `curl \| bash` line that fetched the script — identical trust to the hardcoded vendor one-liners it replaces.
+3. **Nothing fetched at install time is ever executed.** There is no second code path that fetches anything after the script itself has been fetched.
+
+That is mechanical rather than a promise. `CLI_INSTALL_CMD_TRUSTED` is written only from the
+generated block and is the only array the installer ever runs or displays — there is no second
+array a refresh could rewrite, because there is no refresh. `test/cli-catalog-sync.test.ts`
+asserts that the embedded commands are exactly the registry's, and
+`test/install-sh-invariants.test.ts` that nothing in `install.sh` `eval`s.
+
+### bash 3.2
+
+macOS ships bash 3.2 and the documented install is `curl -fsSL <url> | bash` under
+`set -euo pipefail`, so a bash-4 construct is not a warning there — it kills the install. The
+generated block therefore uses parallel indexed arrays with **offset/length windows** into one
+flat array instead of delimiters (a `$HOME` containing a space needs no `IFS` handling, and an
+entry with nothing to contribute gets length 0 and is never iterated). CI runs `bash -n` and
+executes the script inside a real `bash:3.2` container, because the empty-window case is a
+runtime `set -u` abort that `bash -n` cannot see.
+
+## Resolve at call time, never at import
+
+Anything reading the registry must resolve it when it is asked, not when its module is first imported. `sessionModeSchema()`, `allowedEnvPrefixes()`, `dependencyRegistry()` and each resolver's `searchDirs` thunk all re-read the catalog per call.
+
+A module-level const freezes at first import, and the failure is asymmetric: a CLI enabled while the server is running moved the run menu but not the frozen surface, so validation rejected a mode the menu offered, or `codeman doctor` reported a catalog nobody had any more.
+
+## Adding a CLI
+
+1. Add a `CliEntry` to `stock.ts`.
+2. Run `npm run generate:cli-catalog` and commit **both** artifacts (`config/clis.stock.json` and `install.sh`). The installer's detection, its install menu, its reminder text and the Docker agent image all follow from that one step — this is what makes upstream `b6d0f1fa` ("wire OMP into install.sh's CLI detection, it had none") impossible rather than merely fixed.
+3. Add a golden spawn-command pin to `test/cli-registry-spawn-golden.test.ts`, a row to `test/cli-capability-predicates.test.ts`, its remote/docker commands to `test/location-overlay-commands.test.ts`, and its search paths to `test/install-sh-detection-parity.test.ts`.
+4. Only if it cannot install with a plain `npm install -g <pkg>`: give it a layer in `docker/agent.Dockerfile` and set `discovery.install.agentImageLayer: { kind: 'dedicated', reason }` on its entry in `stock.ts`. `test/docker-agent-image-coverage.test.ts` requires both, so an exclusion cannot quietly become an omission. An entry with no `npmPackage` needs only the Dockerfile layer, since it never enters the shared npm layer in the first place.
+5. That is usually all. If you find yourself wanting to add an `if` somewhere, the guard test will tell you — and the answer is a capability field, or a named profile if it genuinely needs to run code.
+
+## See also
+
+- [Agent CLIs](wiki/Agent-CLIs.md) — the user-facing per-CLI guide.
+- `docs/architecture-invariants.md` — the mechanics and the history behind the rules above.
+- `docs/deepseek-integration.md` — why DeepSeek is shaped the way it is.

docs/cron-discovery.md

@@ -44,9 +44,9 @@ records), kept distinct from the existing `ScheduledRun`.
 
 ## 2. Where agent/session types are defined
 
-- `type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini'`
+- `type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini' | 'antigravity' | 'pi'`
   (`src/types/session.ts:43-44`). `shell` covers the brief's "Terminal/custom".
-- CLI availability resolvers in `src/utils/{claude,codex,gemini,opencode}-cli-resolver.ts`.
+- CLI availability resolvers in `src/utils/{claude,codex,gemini,antigravity,opencode,pi}-cli-resolver.ts`.
 - **Integration point:** the job's `agentType` reuses `SessionMode` verbatim.
 
 ## 3. Where input is sent into a session

docs/cron-guide.md

@@ -1,7 +1,7 @@
 # Cron Jobs — User & Operator Guide
 
 Codeman's **Cron** feature lets you save named, recurring jobs that automatically
-spin up a Claude (or shell / OpenCode / Codex / Gemini) session on a schedule and
+spin up a Claude (or shell / OpenCode / Codex / Antigravity / Gemini / Pi) session on a schedule and
 feed it a prompt. Think "cron for agent sessions": _"every weekday at 3am, open a
 Claude session in `~/proj` and tell it to update dependencies and open a PR."_
 
@@ -91,7 +91,7 @@ These map 1:1 to `CronJobSchema` (`src/web/schemas.ts`) and the `CronJob` type
 | Field                      | Required    | Values / limits                                          | Notes                                                                                                                                                                                      |
 | -------------------------- | ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `name`                     | ✅          | 1–200 chars                                              | Display name; also used as the created session's name.                                                                                                                                     |
-| `agentType`                | ✅          | `claude` \| `shell` \| `opencode` \| `codex` \| `gemini` | Reuses Codeman's `SessionMode`. `shell` = a plain terminal.                                                                                                                                |
+| `agentType`                | ✅          | `claude` \| `shell` \| `opencode` \| `codex` \| `gemini` \| `antigravity` \| `pi` \| `grok` | Reuses Codeman's `SessionMode`. `shell` = a plain terminal. ⚠️ A `pi` or `grok` job's readiness poll looks for `❯`/a token count, which neither CLI prints, so it burns the poll budget and then sends the prompt anyway (slower start, still works). |
 | `workingDir`               | ✅          | valid path (allowlist-validated)                         | Validated at **create/update** (must exist, be a directory, and not resolve into a blocked tree — `/etc`, `/root`, `/proc`, `/sys`, `/dev`, or `/` itself) and again **at fire time**.     |
 | `launchCommand`            | —           | ≤ 2000 chars, single line                                | `shell` mode only: sent as the **first input line** once the shell is up, before the prompt. Ignored for other agent types.                                                                |
 | `promptMode`               | ✅          | `inline_text` \| `prompt_file_path`                      | See §5.                                                                                                                                                                                    |

docs/custom-model-endpoints-plan.md

@@ -0,0 +1,375 @@
+# Custom Model Endpoint Profiles (all harnesses, local or cloud)
+
+## Context
+
+The author pays for Claude Code but also runs a capable local model behind an
+OpenAI-compatible server (llama.cpp) — and wants the same mechanism to work
+against a **cloud** OpenAI-compatible endpoint too (e.g. Azure AI Foundry's
+OpenAI-compatible inference endpoint, OpenRouter, a self-hosted gateway).
+Right now every Codeman session mode defaults to its native cloud backend
+with no way to redirect a session at any other endpoint from the UI — the
+closest existing precedent is DeepSeek's server-env-sourced
+`DEEPSEEK_BASE_URL`, which isn't user-facing.
+
+**Scope note**: this plan originally said "local LLM." It now covers any
+OpenAI-compatible endpoint the user configures — local (llama.cpp, Ollama,
+vLLM) or cloud (Azure AI Foundry, OpenRouter, a company gateway). The
+mechanism is identical (a base URL Codeman probes via `GET /v1/models`); the
+only real differences are auth-header convention (cloud endpoints often want
+an `api-key` header, e.g. Azure, rather than `Authorization: Bearer`) and
+that a cloud "model" may actually be a deployment name distinct from the
+underlying model family (Azure AI Foundry deployments) — both are called out
+where they matter below. Naming throughout this plan is **"custom model
+endpoint,"** not "local model," to keep that scope explicit.
+
+### Additional use case: on-premises AI hardware
+
+"Local" isn't limited to a desktop running llama.cpp — a growing category of
+purpose-built, on-premises AI hardware exists specifically to run a serious
+model on-site with an OpenAI-compatible server, and this feature is exactly
+the on-ramp for pointing Codeman at one:
+
+- **NVIDIA DGX Spark** (and the DGX Spark-class "Spark" mini-supercomputer
+  line) — a compact on-prem inference/training box aimed at running large
+  local models with an OpenAI-compatible API surface.
+- **AMD "Strix Halo" (Ryzen AI Max)** on-prem AI mini-PCs — unified-memory
+  APU hardware marketed for local LLM inference, typically fronted by
+  llama.cpp/Ollama/vLLM the same way a home server would be.
+
+Neither needs anything new from this design: both present a standard
+`/v1/models` + `/v1/chat/completions` OpenAI-compatible surface once the
+inference server is running, so they're just another `baseUrl` entry in the
+custom-model-hosts store, same as llama.cpp or a cloud endpoint. The
+justification for building this generically (rather than hardcoding "point
+Claude at my llama.cpp box") is precisely this: **the same endpoint registry
+and per-CLI injection mechanism should work unmodified for any current or
+future OpenAI-compatible box or service** — a home GPU rig today, a Spark or
+Strix Halo appliance tomorrow, a company's on-prem inference cluster after
+that — without Codeman needing to know or care what's actually serving the
+model on the other end of that URL.
+
+A concrete example worth naming: **[Ark0N/Qwen5090](https://github.com/Ark0N/Qwen5090)**
+(from the same GitHub account as this project's owner) is a one-click
+Windows / one-command Linux installer that stands up Qwen3.8-27B locally on
+an RTX 5090 (or another RTX 50-series card with ≥24GB) behind an
+OpenAI-compatible API, served by any of vLLM, NInfer, or llama.cpp — MIT-
+licensed tooling over Apache-2.0 Qwen weights. It's a direct, ready-made
+target for this feature: point a custom-model-hosts entry at whichever
+backend it's running, and it needs nothing further from Codeman's side. It's
+also notable for already wiring up DeepSeek Harness and Claude Code as
+coding agents against that local server itself, which is effectively the
+same "point a Codeman-supported harness at a local endpoint" idea this
+feature is generalizing — worth using as a real-world reference/test target
+once chunk 5 (session integration) exists, alongside the author's own llama.cpp
+box.
+
+Each harness has its own (different-shaped) mechanism for pointing at a
+custom OpenAI-compatible base URL + model — env vars for Claude, a JSON
+config blob for opencode, a TOML file for Codex, etc. The author gave the
+starting recipes for those three; the rest (Gemini, Pi, Grok, DeepSeek, OMP,
+Antigravity) were researched for this plan and are flagged by confidence
+below. A real end-to-end pass against the author's own llama-swap server
+(`scripts/test-local-llm-harnesses.ts`, inside a `codeman/agent:llm-test`
+Docker image with all 9 CLIs installed) then confirmed **claude and
+opencode work end-to-end**, corrected a real Codex config.toml schema bug
+the given recipe had (see the Codex row below), and surfaced that Codex's
+_protocol_ — not just its config shape — does not work against a plain
+OpenAI-Chat-Completions server like llama.cpp/llama-swap at all. Confidence
+below reflects what was actually observed, not just what was planned.
+
+The feature must be:
+
+- **Off by default**, one settings toggle turns it on.
+- Endpoint entry: user gives a base URL — a LAN address or a cloud URL —
+  plus an optional API key, and Codeman calls `GET <baseUrl>/v1/models` to
+  discover and store the available model (or deployment) list.
+- A **new toolbar selector** (separate from the existing Run-mode menu, since
+  it's a modifier on top of whichever harness is already selected/running)
+  lets the user pick "Cloud (default)" — the harness's own native backend —
+  or a model discovered from one of the configured custom endpoints.
+- Picking a custom-endpoint model for an **already-running session restarts
+  that session's CLI process** with the injected env/config pointed at that
+  endpoint (confirmed with the maintainer — these harnesses read endpoint config at
+  process start, not per-turn, so a live hot-swap isn't possible).
+- **New sessions always default back to the harness's native cloud backend.**
+  A custom-endpoint selection is a per-session override, not a sticky global
+  default — starting a fresh CLI (any mode) always launches against its
+  native backend unless the user explicitly picks a custom endpoint for that
+  new session too. The toolbar selector is scoped to "this session," never
+  carried forward as the default for future sessions.
+
+This follows the repo's existing data-driven CLI-registry philosophy
+(`test/cli-registry-no-id-branching.test.ts`): per-CLI behavior is a
+declared capability, never an `if (mode === 'claude')` branch.
+
+## Per-CLI injection recipes (confidence-ranked)
+
+| CLI           | Mechanism                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Confidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `claude`      | Env vars: `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`, `ANTHROPIC_DEFAULT_SONNET_MODEL`/`_HAIKU_MODEL`/`_OPUS_MODEL` (all set to the chosen model/deployment name)                                                                                                                                                                                                                                                                                                                                                                                                        | **Verified end-to-end** against a real llama-swap server — a real "hello world" reply came back. ⚠️ Non-interactive (`-p`) invocations also fire an async session-title-generation call that reuses `ANTHROPIC_DEFAULT_HAIKU_MODEL` and validates it against Claude Code's OWN internal recognized-model list, printing `[claude-code:unrecognized_model]` and, in `-p` mode, hanging the whole invocation rather than just warning. `--settings '{"autoTitle":false}'` does NOT stop this (confirmed); `--bare` does (the warning still prints, but the real prompt runs) — but `--bare` ALSO disables hooks, LSP, plugin sync, and CLAUDE.md auto-discovery, so it is only safe for the standalone one-shot test script, NEVER for a real interactive Codeman session (which depends on hooks for idle detection, trust-dialog auto-accept, etc. — see the External CLI modes section of CLAUDE.md). Whether an INTERACTIVE claude session with a custom model hits the same hang (vs. just a background warning) is untested and should be checked before calling chunk 5/6 done for claude                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `opencode`    | `OPENCODE_CONFIG_CONTENT` env var (already a registry mechanism, `stock.ts:342`) holding a JSON blob: `{"provider":{"custom":{"options":{"baseURL":...,"apiKey":...},"models":{"<name>":{}}}},"model":"custom/<name>"}`                                                                                                                                                                                                                                                                                                                                                 | **Verified by user**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `codex`       | TOML `config.toml`: top-level `model = "<id>"` + `[model_providers.custom]` (`base_url`, `env_key` naming an env var the real API key rides in — never a literal TOML field, since codex's schema has no such field). Written to an isolated dir via `CODEX_HOME` (`stock.ts:405-415`) so the user's own `~/.codex/config.toml` is never touched                                                                                                                                                                                                                        | **Config STRUCTURE verified** against a real codex binary (an earlier `[model].default` table shape was rejected: "invalid type: map, expected a string" — caught live). **Protocol picture more nuanced than a flat break, re-verified live twice on 2026-09-17 against a llama-swap deployment that DOES answer `/v1/responses`** (an earlier test's `Reconnecting...`/`high demand` failure does not reproduce against every llama-swap setup): a plain, no-tool-call chat turn (`codex exec 'reply with just OK'`) returned a real reply. But a real tool-call attempt (`run the shell command: echo hello`) came back as an `agent_message` TEXT item — the tool-call JSON printed as the model's answer, not a `function_call` item codex would actually execute (confirmed via `codex exec --json`'s raw event stream: `item.completed`/`agent_message`, never `function_call`). Since tool execution is what makes codex a coding agent at all, this remains **not usable for real work**, just with a different, more specific failure mode than previously documented — still do not present this as working. Separately, EVERY custom-endpoint codex session also prints `warning: Model metadata for '<id>' not found. Defaulting to fallback metadata...` on launch (confirmed harmless — the successful plain-text reply above still had it): codex's per-model metadata (reasoning tiers, system-prompt templates, context-window figures) comes from `models_cache.json`, a LOCAL CACHE of OpenAI's own hosted model catalog that a custom model can never appear in by construction. No config.toml override exists for it, and the isolated `CODEX_HOME` never gets a `models_cache.json` written into it at all (confirmed: inspected a live, actively-used isolated dir — codex evidently can't reach OpenAI's catalog endpoint for this session and just falls back silently every time, with no file left behind to fix or clean up). Fabricating a fake catalog entry to suppress the warning would mean copying the _shape_ of OpenAI's own proprietary schema — including their real per-model system-prompt content, visible in a genuine `models_cache.json` — for a warning confirmed to have no effect on the actual (broken) tool-calling outcome; not worth building |
+| `gemini`      | Env vars `GOOGLE_GEMINI_BASE_URL` + `GEMINI_API_KEY` + `GEMINI_MODEL`; CLI needs a restart to pick them up                                                                                                                                                                                                                                                                                                                                                                                                                                                              | **Confirmed BROKEN against llama.cpp/llama-swap, unresolved after real investigation.** Setting `GOOGLE_GEMINI_BASE_URL` makes gemini-cli internally select an `AuthType.GATEWAY` auth path (undocumented — inferred from behaviour) with validation requirements distinct from every normal auth mode; a real run against llama-swap fails with `Invalid auth method selected` regardless of what key/format is supplied. Tried and all failed: a Google-format dummy API key, `GOOGLE_GENAI_USE_VERTEXAI=false`, a `GEMINI_DEFAULT_AUTH_TYPE` override, and hand-writing `settings.json` directly. `--skip-trust` was a real, separate fix (without it a trust-folder check silently overrides `--approval-mode yolo` back to `default`) but does not touch this auth failure. Documented as an open gap, not shipped as working — the registry entry and injection code exist and are exercised by the test script, but end-to-end gemini support needs upstream investigation of `GATEWAY` AuthType before it can be called done                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `pi`          | Config file `~/.pi/agent/models.json` with a custom provider whose `models` is an **array** of `{id}` objects (not an object keyed by id) plus `authHeader: true`. Redirected via the child process's own `HOME` env var, isolated per test/session — **not** `PI_CONFIG_DIR`, which does nothing for pi (grepped pi's entire bundled JS source: the string appears nowhere)                                                                                                                                                                                            | **Verified end-to-end** against a real llama-swap server — real "hello world" reply came back. Two real bugs found and fixed before this worked: (1) `PI_CONFIG_DIR` is not read by pi at all — pi hardcodes `~/.pi/agent/models.json` with no dedicated override, so the actual redirect has to be the child process's `HOME`; (2) `models` must be an array of `{id}` objects per pi's own bundled `docs/models.md`, not an object keyed by model id (silently loaded zero models). Also requires an explicit `--model custom/<id>` on invocation — without it pi falls back to its own default provider and fails with "No API key found for the selected model"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `grok`        | TOML `config.toml`: a fixed `[model.codeman-custom]` block (`base_url`, `env_key` naming an env var the key rides in, never a literal TOML field) written to an isolated dir via `GROK_HOME`. Invoked with `-m codeman-custom`                                                                                                                                                                                                                                                                                                                                          | **Verified end-to-end** against a real llama-swap server — real "hello world" reply came back. The ORIGINAL recipe in this table (env vars `GROK_BASE_URL`/`XAI_API_KEY`/`GROK_MODEL`) was flat-out **wrong**, not just unverified: it produced "Not signed in" against a real binary. Grok's real mechanism, confirmed against xAI's own docs and a live binary, is a `config.toml` with a `[model.<name>]` block, redirected via `GROK_HOME`; the key still rides as an env var (`XAI_API_KEY` via `env_key`), just referenced from the TOML rather than read directly                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `deepseek`    | Reuse the **existing** `DEEPSEEK_BASE_URL` + `DEEPSEEK_API_KEY` keys (already declared in `stock.ts`), now with `appendV1Suffix: true` (see confidence). Only `DEEPSEEK_BASE_URL` is in `privilegedEnvKeys` — `DEEPSEEK_API_KEY` deliberately stays clamp-exempt, since a non-granted owner supplying their OWN key removes privilege rather than granting it (adding it to the clamp list was a real regression, caught by `test/deepseek-mode.test.ts` and fixed before merge). No model-selection var — dsh model is a profile composition entry, not a flag/env var | **Root cause of the original `HTTP_404` found and fixed, by reading dsh's own bundled source — the same bar pi/grok's fixes were held to.** Installed `@deepseek-ai/dsh` (all its real published dependencies) into a scratch directory purely to read `@deepseek-ai/dsh-llm-deepseek/lib/index.js`: it builds its request as `fetch(\`${connection.baseURL}/chat/completions\`, ...)`with`baseURL`read straight from`DEEPSEEK_BASE_URL`(or defaulting to DeepSeek's real public API root,`https://api.deepseek.com`, which also carries no `/v1`) — no `/v1` insertion of dsh's own, unlike the OpenAI-SDK convention this recipe originally assumed. llama-swap/llama.cpp only ever serves the OpenAI-conventional `/v1/chat/completions`. Confirmed live: `POST <baseUrl>/chat/completions` → `404`, `POST <baseUrl>/v1/chat/completions` → `200`, on the exact same endpoint — and dsh's own error-message template, `DeepSeek API error (HTTP ${status})`, reproduces the originally reported `dsh: HTTP_404: DeepSeek API error (HTTP 404)` precisely. Fixed by adding `appendV1Suffix` (env kind only, deepseek's entry alone — claude/gemini must NOT get it, since claude was already confirmed working against the unmodified `baseUrl`), which runs `endpoint.baseUrl` through the same `withV1Suffix()` helper `configDir`-kind CLIs already use. ⚠️ Not yet re-run end-to-end with a real `dsh` binary — no install available in this environment (no npm-installed CLI binary in `PATH`, and the `codeman-test-picker` container doesn't bundle it either); the fix is source-confirmed and live-verified at the HTTP level, but a genuine "hello world" reply through `dsh` itself is the remaining step before promoting this to **verified** alongside claude/opencode/pi/grok/omp                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `omp`         | Config file `~/.omp/agent/models.yml` with the same array-shaped `models` + `authHeader: true` fix as pi. Redirected via `HOME`, same reasoning as pi (`PI_CONFIG_DIR` does not relocate omp's config either, despite an earlier CLAUDE.md note claiming it does)                                                                                                                                                                                                                                                                                                       | **Verified end-to-end** against a real llama-swap server — real "hello world" reply came back, after applying the same two fixes as pi (array-shaped `models`, `HOME`-redirect instead of `PI_CONFIG_DIR`) plus an explicit `--model custom/<id>` on invocation. Unverified against omp's own official docs (none are bundled in the install), but empirically confirmed working live                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `antigravity` | No CLI/env/config mechanism found — Antigravity's docs describe only a GUI settings panel, and explicitly say a custom endpoint "cannot currently" become the core reasoning model. **Not implemented**; toolbar entry stays disabled for this mode with an explanatory tooltip                                                                                                                                                                                                                                                                                         | No known mechanism                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+
+Everything web-researched-but-unverified gets implemented but must be
+smoke-tested against real installs of those CLIs before being called done —
+call this out explicitly when implementing, don't just ship on faith.
+
+**Cloud-endpoint specifics** to keep in mind per recipe above: an Azure AI
+Foundry-style endpoint typically wants the API key in an `api-key` header
+rather than (or in addition to) `Authorization: Bearer`, and its "model" is
+often a deployment name rather than the underlying model family name — the
+discovery step (`GET /v1/models`) still works the same way against Azure AI
+Foundry's OpenAI-compatible endpoint shape, but a user may need to type the
+deployment name manually if it isn't returned as expected.
+
+## Architecture
+
+### 1. Registry: new `capabilities.customModelInjection` field
+
+Extend `src/config/cli-registry/types.ts` / `schema.ts` with a discriminated
+union on each `CliEntry.capabilities`:
+
+```ts
+type CustomModelInjection =
+  | { kind: 'env'; baseUrlVar: string; apiKeyVar: string; modelVars: string[] }
+  | { kind: 'configContentEnv'; envVar: string; template: 'opencode-json' }
+  | {
+      kind: 'configDir';
+      dirEnvVar: string;
+      fileName: string;
+      template: 'codex-toml' | 'pi-models-json' | 'omp-models-yml';
+    }
+  | { kind: 'unsupported' };
+```
+
+Declared per stock.ts entry per the table above. A pure function in a new
+`src/custom-model-injection.ts` (`buildCustomModelInjection(entry, endpoint, modelId)`)
+turns `(CliEntry, endpoint, modelId)` into either an `envOverrides` object
+(kind `env`/`configContentEnv`) or a `{ dirEnvVar, files: [{path, content}] }`
+descriptor (kind `configDir`) — unit-testable with no IO, mirroring how
+`session-cli-builder.ts` is pure. The `configDir` kind additionally needs an
+IO wrapper that writes those files under
+`dataPath('custom-model-configs/<sessionId>/')` (new dir, cleaned up on
+session delete — same lifecycle as other per-session generated state).
+
+### 2. Endpoint registry: `src/custom-model-hosts.ts`
+
+Same read-array/write-array shape as `src/remote-hosts.ts` /
+`src/webview-store.ts`: `~/.codeman/custom-model-hosts.json` holding
+`CustomModelEndpoint[] = { id, label, baseUrl, apiKey?, authStyle?: 'bearer'|'api-key'|'both', models?: string[], lastDiscoveredAt? }`.
+`authStyle` defaults to `'both'` (send both header conventions on the
+discovery probe, same approach the smoke-test script below uses) so one
+endpoint entry works whether it's llama.cpp or Azure without the user having
+to know which header their box wants in advance.
+
+New route file `src/web/routes/custom-model-routes.ts` (registered in the
+routes barrel), mirroring `case-routes.ts`'s remote/docker-host CRUD
+(`GET/POST/PUT/DELETE /api/model-endpoints`, admin-gated in multi-user mode
+the same way) plus:
+
+- `POST /api/model-endpoints/:id/discover-models` — fetches
+  `${baseUrl}/v1/models`, stores the `data[].id` list, returns it. Bounded
+  timeout, and run the target through the **same SSRF egress guard already
+  used for web tabs** (`webview-egress-policy.ts` — reject link-local/cloud
+  metadata addresses) — this still matters for a cloud URL too, since the
+  guard is about preventing a redirect to internal infra, not about
+  local-vs-cloud.
+
+**Why discovery rather than a free-text model field**: it removes the one
+piece of configuration most likely to trip a user up — hand-typing the
+exact model identifier a given inference server expects, which varies by
+server and is an easy source of a silent "model not found" failure with no
+useful error surfaced back through a CLI's own startup. Discovery also
+means this design is not limited to a single-model box: a **multi-model
+gateway** such as **[llama-swap](https://github.com/mostlygeek/llama-swap)**
+(hot-swaps between several loaded llama.cpp model configs behind one
+OpenAI-compatible endpoint) or a vLLM/LiteLLM/Ollama instance serving
+several models advertises ALL of them through the same `/v1/models` call —
+so one endpoint entry surfaces every model that gateway can serve, with no
+extra per-model configuration on Codeman's side at all.
+
+### 3. Settings
+
+- New synced boolean `customModelEndpointsEnabled` in `SettingsUpdateSchema`
+  (`src/web/schemas.ts`), default `false`, documented inline like
+  `readMyMindEnabled`/`workspaceHooksEnabled`.
+- New `.set-group` "Custom Model Endpoints" inside the **Agents & CLIs**
+  section (`settings-clis`, `index.html:2150+`) with the enable toggle plus
+  a list-editor (add/refresh-models/delete rows) for endpoints — closest
+  existing precedent is the respawn-presets array editor
+  (`schemas.ts:1285-1305`, `index.html:1243-1244`) for add/apply/delete-by-id
+  semantics, backed by the new CRUD routes above.
+
+### 4. Toolbar UI
+
+> **Superseded.** This section describes the toolbar-button design as originally
+> planned. What actually shipped is a Run-menu picker instead: one generated entry
+> per (capable harness, saved endpoint) pair directly in the existing `#runModeMenu`
+> dropdown, rather than a separate `#customModelBtn`/`#customModelMenu` surface. See
+> [`docs/custom-model-endpoints.md`](custom-model-endpoints.md#the-run-menu-picker)
+> for the current design; the sections below (session-restart mechanics, security)
+> remain accurate regardless of which UI calls the underlying route.
+
+- New header/toolbar button (e.g. `#customModelBtn`, `btn-toolbar
+btn-custom-model`), marker-hidden by default (`btn-custom-model--hidden`)
+  and revealed by `applyHeaderVisibilitySettings()` only when
+  `customModelEndpointsEnabled` is on — same pattern as the File
+  Viewer/Cron buttons.
+- Clicking opens a dropdown (`#customModelMenu`, same `.run-mode-menu`-style
+  markup as the existing Run-mode gear menu) listing "Cloud (default)" plus
+  every discovered model, grouped by endpoint. An entry is disabled with a
+  tooltip when the active session's CLI has `customModelInjection.kind ===
+'unsupported'` (Antigravity) or none declared.
+- Selecting an entry calls a new route:
+  `POST /api/sessions/:id/custom-model { endpointId, modelId } | { clear: true }`.
+  Server: resolve the CLI entry for `session.mode`, build the injection via
+  §1, persist it as a new `session.customModel` state field (surfaced in
+  `toState()`/SSE so the tab can show a small badge, e.g. "🖥 qwen3 (local)"
+  or "☁ gpt-4o-mini (azure)", and the choice survives reload), merge into
+  the session's `envOverrides`, and **respawn the pane's CLI process**
+  through the same respawn/interactive-restart path
+  `session.ts`/`tmux-manager.ts` already use for effort/model changes
+  (`_configureCliEnv()` + `applyEnvOverrides()` at spawn time) — reuse,
+  don't reinvent, the existing kill-and-relaunch-in-pane machinery.
+- New-session creation deliberately does **not** inherit a prior custom-
+  endpoint choice: `buildEnvOverrides()` (session-ui.js) never carries the
+  toolbar selection forward to the next `run()` call. Every new session
+  starts on its native backend; picking a custom endpoint in the toolbar for
+  a session applies only to that session (and, if done before Run is
+  clicked, to the one session about to be created — not to sessions created
+  afterward).
+
+### 5. Multi-user security clamp
+
+Every new env var this feature introduces that can redirect a session's
+traffic (and thus wherever its credentials go) — `ANTHROPIC_BASE_URL`,
+`GOOGLE_GEMINI_BASE_URL`, `GROK_BASE_URL`, the `CODEX_HOME`/`PI_CONFIG_DIR`
+dir-redirects, plus the already-privileged `DEEPSEEK_BASE_URL` — must be
+added to each CLI's `capabilities.privilegedEnvKeys` so
+`clampEnvOverridesForOwner()` strips them for a non-granted multi-user
+owner, exactly the precedent already documented for `DEEPSEEK_BASE_URL`/
+`OMP_AUTH_BROKER_URL`. This matters _more_, not less, now that endpoints can
+be cloud URLs: redirecting a non-granted user's session to an attacker's
+cloud endpoint is a credential-exfiltration path, not just a mischief
+redirect to a LAN box. Endpoint CRUD itself stays admin-only in multi-user
+mode, same as remote/docker hosts.
+
+## Files touched (representative, not exhaustive)
+
+- `src/config/cli-registry/types.ts`, `schema.ts`, `stock.ts` — new capability + per-entry declarations
+- `src/custom-model-injection.ts` (new) — pure per-CLI descriptor builder + unit tests
+- `src/custom-model-hosts.ts` (new) — endpoint store
+- `src/web/routes/custom-model-routes.ts` (new) — CRUD + discovery route
+- `src/web/routes/session-routes.ts` — `POST /api/sessions/:id/custom-model`, clamp wiring
+- `src/web/schemas.ts` — `customModelEndpointsEnabled`, endpoint/discover payload schemas, privileged-key updates
+- `src/session.ts` — `customModel` state field, `toState()` surface
+- `src/web/public/index.html`, `settings-ui.js`, `session-ui.js`, `styles.css` — settings group, toolbar button/menu, badge, accent CSS
+- `src/web/sse-events.ts` + `constants.js` — if a dedicated SSE event is warranted for the badge (or just ride existing session-update broadcasts)
+- `test/fixtures/mock-openai-server.ts` (new) + `test/custom-model-injection-contract.test.ts` (new) — see Mock-server validation below
+- `scripts/test-local-llm-harnesses.ts` (already added, this branch; run via `npx tsx`) — the standalone real-CLI-and-real-endpoint smoke test, supporting any `--base-url` (local or cloud). Dynamic: derives its harness list and every env var/config it injects from the live CLI registry + `buildCustomModelInjection()` rather than a second hand-maintained copy — only the one-shot invocation flags (`ONE_SHOT` table) are CLI-specific info the registry doesn't model and stay hand-maintained
+- `docs/custom-model-endpoints.md` (new) + a CLAUDE.md pointer bullet under External CLI modes / envOverrides
+
+## Mock-server validation strategy (CI-runnable, no real CLI binaries needed)
+
+Spawning nine real CLI binaries in CI isn't realistic, and neither the author's
+llama.cpp box nor a real cloud subscription can be a CI dependency. So the
+injection _logic_ gets a tier of automated coverage that sits between the
+pure unit tests and the live manual checks in Verification:
+
+1. **`test/fixtures/mock-openai-server.ts`** — a small in-process HTTP
+   server (plain `http.createServer`, no external deps, port picked per the
+   existing `const PORT = 3150+` convention) that:
+   - Serves `GET /v1/models` → a fixed fake model list (`{data:[{id:'qwen3'},...]}`),
+     for testing the discovery route.
+   - Serves `POST /v1/chat/completions` (OpenAI shape) **and**
+     `POST /v1/messages` (Anthropic Messages-API shape, since that's what
+     `ANTHROPIC_BASE_URL` traffic looks like) and records every request it
+     receives (headers, body, path) into an array the test can assert on —
+     including which auth header style it saw, so the `authStyle: 'both'`
+     default and Azure's `api-key` convention both get real coverage.
+   - Returns a minimal valid completion so a client library doesn't choke
+     on the response shape.
+
+2. **`test/custom-model-injection-contract.test.ts`** — for every CLI with a
+   `customModelInjection` capability (i.e. every row in the table above
+   except `antigravity`):
+   - Point a fixture `CustomModelEndpoint` at the mock server's URL.
+   - Call `buildCustomModelInjection(entry, endpoint, modelId)` (the pure
+     function from §1) to get the real env vars / config-file content that
+     would be injected into that CLI's session.
+   - Replay those exact values through a minimal HTTP request shaped the
+     way that CLI is documented to send it (Anthropic Messages shape for
+     claude; OpenAI chat-completions shape for opencode/codex/pi/grok/omp;
+     `GOOGLE_GEMINI_BASE_URL`'s OpenAI-compat shape for gemini; dsh's
+     provider call for deepseek) against the mock server.
+   - Assert the mock server received the request **at the injected
+     `baseUrl`**, with **the injected API key** in the expected header, and
+     **the injected model id** in the body/path — i.e. prove the values
+     Codeman computes are internally consistent and would reach the right
+     place with the right identifiers, end to end, in CI, on every push.
+   - Also cover the `configDir` kind (codex/pi/omp): assert the written
+     `config.toml`/`models.json`/`models.yml` file parses and contains the
+     same base URL/key/model, and that it's written under the isolated
+     per-session dir rather than the user's real config path.
+
+3. **Explicit, stated limitation** (goes in the test file's `@fileoverview`
+   and in this doc, not left implicit): this proves _"if the CLI honors its
+   documented env/config contract, it will hit the right endpoint with the
+   right model."_ It does **not** prove the real CLI binary actually reads
+   that env var / config file the way its docs say — that's still the job
+   of the live manual checks in Verification step 4-5 below, and is exactly
+   why the confidence table above did not stop at "researched" — every CLI
+   except antigravity (no mechanism at all) has since been run against a
+   real llama-swap server via `scripts/test-local-llm-harnesses.ts`:
+   claude/opencode/pi/grok/omp are confirmed PASS end-to-end, codex is
+   confirmed FAIL for a real documented protocol reason (Responses-API-only
+   since Feb 2026), and gemini/deepseek are confirmed reaching the server
+   but failing for reasons not yet root-caused (see their table rows). The
+   mock-server suite catches regressions in Codeman's own logic; it cannot
+   catch a CLI changing its env-var name in a future release, or a real
+   cloud endpoint behaving differently from a local llama.cpp box.
+
+## Verification
+
+1. `npm run typecheck && npm test` after each slice — this now includes the
+   mock-server contract suite from above, so injection-logic regressions
+   are caught automatically without touching real infrastructure.
+2. Unit tests for `buildCustomModelInjection()` per CLI kind (pure, no IO).
+3. Route tests (`app.inject`) for the new CRUD + discover-models endpoint
+   (mock `fetch` for `/v1/models`), and for the multi-user clamp on the new
+   privileged keys (mirror `test/routes/external-cli-bypass-clamp.test.ts`).
+4. **Standalone real-binary smoke test**: `scripts/test-local-llm-harnesses.ts`
+   exercises every harness the CLI registry declares `customModelInjection`
+   support for against a real `--base-url` — local or cloud — outside of
+   Codeman's UI entirely, and is DYNAMIC (reads `enabledClis()` + calls the
+   real `buildCustomModelInjection()`, so a future registry change is picked
+   up automatically with zero edits to the script). Already run to
+   completion against the author's llama-swap server (a LAN address,
+   inside a `codeman/agent:llm-test` Docker image with all 9 CLI binaries):
+   claude/opencode/pi/grok/omp **PASS**, codex **partially works and still
+   isn't usable** (plain chat succeeds against a llama-swap deployment that
+   answers `/v1/responses`, but a real tool-call attempt comes back as
+   inert text rather than an executable `function_call` — see the
+   confidence table row for the full, re-verified picture), gemini/deepseek
+   **UNCONFIRMED**
+   (reach the server, fail for undiagnosed reasons — see their table rows),
+   antigravity **SKIP** (no mechanism). Re-run this against a real cloud
+   endpoint (e.g. an Azure AI Foundry deployment) once one is available, to
+   prove the `authStyle`/deployment-name handling holds up outside llama.cpp.
+5. Once the full feature (not just the standalone script) is built: add an
+   endpoint via the real UI, hit discover-models, confirm the returned model
+   list, pick Claude + the model on a real session, confirm via
+   `tmux -L codeman capture-pane`/`tmux showenv -t <pane>` that
+   `ANTHROPIC_BASE_URL`/`ANTHROPIC_API_KEY`/`ANTHROPIC_DEFAULT_*_MODEL` are
+   set post-restart, and confirm the endpoint's own logs show the next
+   prompt actually landing there. Repeat for opencode and Codex at minimum
+   before considering this shippable; spot-check the web-researched CLIs
+   and correct the plan's confidence table with what's actually observed.
+6. `npm run lint && npm run format:check`.
+7. Update `CHANGELOG.md`/changeset per the COM workflow when shipping.

docs/custom-model-endpoints.md

@@ -0,0 +1,563 @@
+# Custom Model Endpoint Profiles
+
+Point any Codeman-supported harness — Claude, opencode, Codex, Gemini, Pi,
+Grok, DeepSeek, or OMP — at a custom OpenAI-compatible endpoint instead of
+its native cloud backend, for a given session. "Custom endpoint" covers both
+**local** hardware (llama.cpp, Ollama, vLLM, a home GPU rig, or purpose-built
+boxes like NVIDIA DGX Spark or AMD Strix Halo mini-PCs) and **cloud**
+services (Azure AI Foundry's OpenAI-compatible endpoint, OpenRouter, a
+company gateway) — anything answering `GET /v1/models` and
+`POST /v1/chat/completions` in the standard shape. Design doc, per-CLI
+recipe confidence table, and security reasoning:
+[`custom-model-endpoints-plan.md`](custom-model-endpoints-plan.md).
+
+> **Status**: fully wired end to end — registry capability, the injection
+> engine, the endpoint store + discovery route, both the restart-in-place
+> apply route (Claude) and the one-shot quick-start launch path (every
+> other supported harness), a settings-panel CRUD surface, and the Run-menu
+> picker described below. Antigravity has no known custom-endpoint
+> mechanism and is not supported. The HTTP API (examples below) still works
+> directly and is what the picker itself calls under the hood.
+
+## Turning it on
+
+App Settings → Models → **Custom model endpoints** (synced setting
+`customModelEndpointsEnabled`, default **OFF**). Turning it on does two
+things: it reveals the endpoint list/add/edit/discover panel in that same
+settings section, and it makes the Run menu offer a generated entry per
+(harness, endpoint) pair — see "The Run-menu picker" below. The API
+equivalent:
+
+```bash
+curl -sk -X PUT https://localhost:3000/api/settings \
+  -H 'Content-Type: application/json' \
+  -d '{"customModelEndpointsEnabled": true}'
+```
+
+## Adding an endpoint
+
+Via App Settings → Models → Custom model endpoints → **+ Add endpoint**, or
+directly:
+
+```bash
+curl -sk -X POST https://localhost:3000/api/model-endpoints \
+  -H 'Content-Type: application/json' \
+  -d '{"id": "llama-box", "label": "Home llama.cpp", "baseUrl": "http://192.168.1.50:8080"}'
+```
+
+`apiKey` is optional (most local servers don't check it). `authStyle`
+(`bearer` | `api-key`, default `bearer`) controls which auth header
+convention discovery uses: `bearer` is `Authorization: Bearer <key>`
+(llama.cpp, OpenAI-compatible servers, most gateways), `api-key` is the
+`api-key: <key>` header Azure AI Foundry wants. There is deliberately no
+"send both" option: measured against a real llama-swap server, a request
+carrying both headers hung indefinitely. `baseUrl` must be `http(s)`, carry
+no embedded credentials, and may not point at a link-local or cloud-metadata
+address; discovery re-checks the address the name actually resolves to.
+
+Discover its available models:
+
+```bash
+curl -sk -X POST https://localhost:3000/api/model-endpoints/llama-box/discover-models
+```
+
+This calls the endpoint's own `GET /v1/models` and stores the returned list
+on the endpoint record; `GET /api/model-endpoints` lists everything
+configured, `PUT`/`DELETE /api/model-endpoints/:id` update or remove one.
+Endpoint management is admin-only in multi-user mode, same as remote/docker
+hosts — these are machine-level infra, not per-user settings.
+
+**Context length is discovered too, opportunistically and safely.** The plain
+`GET /v1/models` response has no context-window field. Discovery only ever
+looks for one for a model llama-swap's own response already reports
+`status.value === "loaded"` for — never for an unloaded one, because
+llama-swap treats `?model=` as a routing hint and asking about a model that
+isn't loaded risks triggering an actual (slow, GPU-swapping) load as a side
+effect of what should be read-only discovery. A server with no `status` field
+on any entry at all (not llama-swap) gets no context-length enrichment,
+rather than guessing. A model's previously-learned context length survives a
+later cycle where it wasn't the loaded one; it's dropped only once the model
+disappears from the endpoint's list entirely. Stored per model in
+`modelContextLengths` and applied automatically (see "Applying a model to a
+session" below) so a CLI that would otherwise assume a large default context
+window for an unrecognized model id stops silently overflowing a much
+smaller real one.
+
+**Where that number actually comes from matters, and got this wrong once
+already.** The first cut read it from llama.cpp's own
+`GET /props?model=<id>` (`n_ctx`) — plausible, and it worked in testing, but
+confirmed live to be actively WRONG for a `--fit-ctx`-launched llama-swap
+backend: `/props` reported `n_ctx: 154112` for a model llama-swap itself had
+launched with `--fit-ctx 16384`, and the real server then refused a request
+right at that real 16384-token limit — `/props`'s `n_ctx` appears to report
+the model's theoretical/trained maximum there, not the runtime-configured
+one. Discovery now parses the REAL configured size straight out of
+llama-swap's own launch command instead (`GET /running`'s `cmd` field —
+`--fit-ctx <N>` first, then the plain llama.cpp `-c`/`--ctx-size` a
+hand-written command might use), and only falls back to the `/props` probe
+when `cmd` states no recognizable flag at all.
+
+**File size is discovered too, when the server states one.** llama-swap
+writes a GB figure into an auto-discovered model's own `description`
+(`"Auto-discovered 16.35 GB - parameters auto-fitted by llama.cpp"`), parsed
+into `modelSizesGB` — unlike context length, this needs no `/props` probe
+(the figure is right there in the `/v1/models` response) and so is populated
+for every model regardless of loaded state. A hand-configured profile's own
+description has no such figure and correctly gets no entry, never a guess.
+Used only to label the Run-menu picker's "loading model" banner (e.g.
+"Loading qwen3.8-27b-ud-q4_k_xl (16.4 GB) on llama-swap..."); never anything
+a server-side check relies on.
+
+**The loading banner is unbounded by design, and says so — no countdown, no
+automatic give-up.** An earlier version scaled an expected-time estimate and
+a timeout off the model's file size and auto-closed the session once that
+elapsed, but a real load's actual duration depends on hardware this feature
+has no way to know (VRAM, storage speed, whatever else is contending for the
+GPU) — any fixed number was a guess dressed up as a fact, and a model that
+genuinely takes 10+ minutes on slower hardware would just get killed
+mid-load by its own display. The banner now says outright that it can take a
+while depending on hardware and model size, polls
+`GET /api/model-endpoints/:id/running-status` every second for as long as it
+takes, and carries a **Cancel** button (rendered on the banner itself) that
+ends the wait and closes the session the load was for — the user's own call
+on when it's taking too long, not a fixed number baked into the client.
+
+**The banner's second line is the real backend log line, not a guess.**
+llama-swap's `GET /api/events` SSE stream carries the actual `llama-server`
+process's own stdout — `load_model: loading model '<path>'`,
+`llama_server: model loaded`, tokenizer warnings, all of it — tagged
+`source: "upstream"`, distinct from llama-swap's own `source: "proxy"`
+request-access lines. `running-status`'s response now includes `logLine`
+(via `getLatestLlamaSwapLogLine`), and the banner shows it on its own line
+under the disclaimer, e.g. "llama.cpp: load_model: loading model '...'" —
+confirmed live end-to-end through a real forced swap, sequentially showing
+the model path, a tokenizer warning, then staying on whatever llama.cpp last
+printed once the load goes quiet (never cleared back to blank). ⚠️
+**`GET /logs` — the endpoint this feature's own first cut was built
+against — turns out to carry ONLY llama-swap's own proxy request-access
+log.** Confirmed live it never showed a single backend line, even seconds
+after a real, verified model swap; `/api/events`'s `logData` frames are the
+only source that actually has it, and its own `source` field (`upstream` vs
+`proxy`) is what `getLatestLlamaSwapLogLine` filters on. One `/api/events`
+connection is held open per endpoint and reused across every session
+watching a load on it (confirmed live to stay open indefinitely, unlike
+`/logs`, which closes after a fixed ~100KB), idle-closed after 30s of nobody
+polling it (`pruneIdleLlamaSwapLogTails`, same 20s sweep as the
+swap-displacement check below).
+
+`defaultModelId` names which discovered model the picker pre-marks for that
+endpoint — the settings panel's Edit form exposes it as a select populated
+from the endpoint's own discovered `models`, and the route refuses a value
+that isn't one of them. It is applied automatically only when the endpoint
+has exactly one discovered model (nothing to choose); with two or more it
+is a pre-selection in the model-picker dialog below, never a silent default.
+Re-discovering drops a default that no longer appears in the fresh list
+rather than carrying an invalid one forward.
+
+**Model lists refresh themselves.** A background sweep (`server.ts`,
+`CUSTOM_MODEL_REDISCOVER_INTERVAL_MS`, every 5 minutes) re-discovers every
+saved endpoint the same way the manual `POST .../discover-models` route
+does, best-effort per endpoint — one being unreachable on a given cycle
+never blocks the others. Off under `npm test`, same reasoning as the Codex
+plan-usage poll it sits beside: no real network to hit, no server instance
+to keep the timer alive for.
+
+## The Run-menu picker
+
+With the setting on and at least one endpoint carrying a discovered model,
+the toolbar's Run dropdown grows a **Custom Endpoints** section: one entry
+per (harness that can redirect to a custom endpoint, saved endpoint) pair,
+e.g. "Claude Code (llama.cpp)". The harness list is read off the CLI
+registry's own `capabilities.customModelInjection` at page render
+(`window.__codemanCustomModelClis`, `server.ts`) — never a hardcoded id list
+in the frontend — so a CLI whose injection recipe lands later shows up with
+no frontend change, and Antigravity (`unsupported`) never does.
+
+Picking an entry re-fetches the endpoint (`selectCustomModelEntry()`,
+`session-ui.js`) rather than trusting anything cached from the dropdown's
+own render — the model list can have changed via the 5-minute sweep above
+or a settings-panel edit since the menu opened. With exactly one discovered
+model it runs straight away; with two or more, a small modal
+(`#customModelPickModal`) lists them and asks which one to use for this
+launch, with the endpoint's `defaultModelId` marked but not auto-chosen —
+the point of asking is letting one launch deliberately differ from the
+saved default, not just confirming it.
+
+The modal promotes exactly one row to the top of the list rather than
+always showing raw discovery order, so the zero-wait choice is the one
+under your thumb:
+
+- **"Currently loaded"** — a model from this host's own list that
+  llama-swap reports `ready` right now, queried via
+  `GET /api/model-endpoints/:id/running-status`. Bounded client-side to
+  ~800ms (`Promise.race`), on top of the route's own 5s server-side
+  timeout, so an endpoint that is asleep or firewalled cannot leave the
+  modal invisible for the full 5s after the Run menu has already closed.
+- **"Last used"** — shown only when nothing is currently loaded: the model
+  actually launched last for this exact (harness, endpoint) pair, read
+  from the per-device `codeman:customModelLastUsed:<mode>:<endpointId>`
+  localStorage key. Written by `_runCustomModelEntryViaRestart` (claude)
+  and `_quickStartWithCustomModelConfirm` (every one-shot launch; the
+  `runCustomModelEntry` entry point itself only dispatches between the
+  two) only once the model is actually applied, never on the mere click —
+  declining the context-window warning means this exact model cannot work
+  with this CLI at all, so promoting it next time would be actively wrong,
+  not just premature.
+
+Neither tag reorders anything past that one promoted row. The "Default"
+pill is a separate span, not a third value of the same slot: a promoted
+row that is also the endpoint's `defaultModelId` shows both tags (on a
+single-purpose GPU box that is the common case, and an exclusive slot
+silently dropped the Default marking for exactly that row), and a row
+with neither promotion nor default shows no tag at all.
+
+**How the launch itself applies the endpoint depends on the harness.** For
+opencode, Codex, Gemini, Pi, Grok, DeepSeek and OMP (`runCustomModelEntry` →
+`_runCustomModelEntryOneShot`), the endpoint/model is folded into the SAME
+`POST /api/quick-start` call that creates the session (`customModel` field),
+so the session launches directly on the endpoint — no restart, no visible
+relaunch. Claude (`_runCustomModelEntryViaRestart`) still uses the original
+two-step design: the launch runs a single native session exactly the way its
+own Run-menu entry would, then **waits for the new session to go idle**
+(`GET .../wait?until=idle`, bounded at 20s — a normal 200 either way, never
+an error, per the wait endpoint's own contract) before applying the endpoint
+via the restart route below. That wait exists because a freshly launched CLI
+reports itself as `busy` for its own startup (a boot spinner, a
+workspace-trust check) well before the apply call would otherwise reach it,
+and the apply route correctly refuses to restart a session mid-turn — a
+fresh boot looks exactly like one from the outside. A session still busy
+after the wait reaches the apply call anyway and gets that route's own
+honest `SESSION_BUSY` error, now visible as a sticky toast with a close
+button rather than a generic message that vanished in three seconds. Claude
+stays on this path because its own restart (`--resume`-based, keeping the
+conversation) is far less jarring than the other seven's, and `runClaude()`'s
+multi-tab launch and docker-config-drift confirm/retry loop make folding it
+into the one-shot path separate work. It is a
+one-off "try this endpoint" action, not a sticky mode: the plain Run button
+still means "this harness, native cloud" afterward. Entries are hidden
+entirely for a remote or Docker active case, since the apply route refuses
+both (see the next section).
+
+## Launching directly on an endpoint (no restart)
+
+```bash
+curl -sk -X POST https://localhost:3000/api/quick-start \
+  -H 'Content-Type: application/json' \
+  -d '{"caseName": "myapp", "mode": "codex", "customModel": {"endpointId": "llama-box", "modelId": "qwen3"}}'
+```
+
+`POST /api/quick-start`'s `customModel` field (`{endpointId, modelId,
+confirmed?}`) computes the same injection the restart route below does, but
+BEFORE the session exists — the session is minted its own id up front
+(`crypto.randomUUID()`), the injection (env vars, and for a `configDir`-kind
+CLI, the written config file) targets that real id, and the session launches
+already pointed at the endpoint. No restart, because there was never a
+native-backend launch to restart away from. Runs the same llama-swap
+conflict check as the restart route (below) — a `409`-shaped
+`{requiresConfirmation, currentlyLoadedModel, affectedSessions}` response
+with no session created, resolved by retrying with `confirmedSwap: true` — and
+is refused the same way for a remote or Docker case. This is what the
+Run-menu picker uses for opencode, Codex, Gemini, Pi, Grok, DeepSeek and OMP;
+Claude still uses the restart route below (see "The Run-menu picker" above
+for why).
+
+## Applying a model to an ALREADY-RUNNING session
+
+```bash
+curl -sk -X POST https://localhost:3000/api/sessions/<sessionId>/custom-model \
+  -H 'Content-Type: application/json' \
+  -d '{"endpointId": "llama-box", "modelId": "qwen3"}'
+```
+
+This computes the CLI-specific env vars / config for that session's mode
+(see the recipe table in `custom-model-endpoints-plan.md`) and **restarts the session's
+CLI process in place** — same pane, same tmux session, fresh env. That
+restart is necessary, not incidental: every supported harness reads its
+endpoint config at process start, not per-turn, so there is no live
+hot-swap. A Claude session is relaunched with `--resume <conversation> ||
+--session-id <id>`, so it continues the conversation it was on; pi, omp and
+grok are relaunched with the `--model` value that selects the injected
+provider (`custom/<modelId>` for pi and omp, `codeman-custom` for grok),
+since for those three the config file alone does not switch the model.
+**Remote (SSH) and Docker sessions are refused** (400) for now: their restart
+reattaches the durable remote/in-container tmux rather than relaunching the
+agent, so the selection would report success and change nothing.
+
+**Claude gets two more env vars when known/applicable, both declared on its
+registry entry (`contextLengthVar`/`configDirVar`), not hardcoded here:**
+
+- `CLAUDE_CODE_MAX_CONTEXT_TOKENS` is set to `modelId`'s discovered context
+  length (see the discovery section above) whenever one is known. Without
+  it, Claude Code assumes a large (200k) window for any unrecognized custom
+  model id and never compacts, which reliably overflows a much smaller real
+  local context — confirmed live: a stock ~33.7K-token system prompt against
+  a 16384-token llama-swap model failed with `exceeds the available context
+size`. No entry for the model in `modelContextLengths` means the var is
+  simply omitted, never a guess. ⚠️ **This var only affects when Claude
+  Code compacts conversation _history_ — it cannot fix a model whose real
+  context is smaller than Claude Code's own fixed per-turn overhead**
+  (system prompt + tool schemas, empirically ~36.4K tokens, confirmed live
+  via an `in:0 out:0` failure on the very first message, before any
+  history exists to compact). No context-length declaration changes that
+  fixed overhead, so a model below the safe floor fails outright on
+  message one regardless of what this var says. See "Context-window floor
+  warning" below for how Codeman catches this case before launching
+  instead of after.
+- `CLAUDE_CONFIG_DIR` is pointed at the same isolated per-session directory
+  the `configDir`-kind CLIs use (empty, no files written into it), so the
+  injected `ANTHROPIC_API_KEY` never shares a directory with a stored
+  claude.ai OAuth login. Claude Code still prints "Both claude.ai and
+  ANTHROPIC_API_KEY set" when the two coexist in the same config directory —
+  cosmetic (confirmed live: the API key wins for actual requests either way,
+  visible in the terminal's own `API Usage Billing` line) but worth
+  eliminating rather than living with. The directory's `projects`
+  subdirectory is symlinked (a junction on Windows) back to the real
+  `~/.claude/projects` so the response viewer, subagent windows and Read My
+  Mind keep working for that session — the same trade-off and fix documented
+  for a manually-set `CLAUDE_CONFIG_DIR` in
+  [`docs/wiki/Agent-CLIs.md`](wiki/Agent-CLIs.md), just applied
+  automatically here. Best-effort: a platform that refuses the symlink keeps
+  the pre-existing blind-response-viewer side effect rather than failing the
+  whole custom-model apply over it. ⚠️ **This relocates the whole `.claude`
+  tree, not just transcripts**: a custom-model Claude session also loses the
+  user's global `settings.json`, user-level skills (the codeman agent skill
+  included), user-level agents and commands, and the MCP servers configured
+  in `~/.claude.json` — none of those are symlinked back, only `projects` is.
+  A fine trade for "point this session at my local llama.cpp," but worth
+  knowing before it surprises you mid-session.
+
+**That isolated directory needed one more fix to actually be usable
+non-interactively.** An otherwise-empty `CLAUDE_CONFIG_DIR` has none of a
+real profile's prior "Detected a custom API key — use it?" approvals, so
+without more, Claude Code stops and asks that on _every single launch_ —
+confirmed live, and with nobody at a TTY to answer, its own default answer
+("No") silently refuses the very key this feature just injected, which
+looks like the endpoint being ignored entirely. `customModelInjection`'s
+`apiKeyTrustFile` (`{ relPath: '.claude.json', shape:
+'claude-api-key-responses' }` on claude's entry) pre-seeds that exact
+approval: the apply step merges `customApiKeyResponses.approved: [apiKey]`
+into `<configDir>/.claude.json`, the same field a real answered prompt
+itself writes to (confirmed against a real file after answering by hand
+once) — this answers the prompt in advance rather than bypassing it. The
+merge preserves whatever else the CLI already wrote into that file on an
+earlier launch in the same isolated directory (`userID`, `numStartups`,
+earlier approved keys), and a missing or corrupt file is treated as empty
+rather than failing the apply.
+
+**A fresh `CLAUDE_CONFIG_DIR` isn't just missing that one approval — Claude
+Code treats it as a brand-new profile and replays its ENTIRE first-run
+sequence on every launch: the theme picker, the security-notes screen, the
+per-project "trust this folder?" dialog, and (running with
+`--dangerously-skip-permissions`) a one-time warning about bypassing
+permissions.** Confirmed live: none of these show up again for a real,
+already-onboarded profile, but every custom-model session gets a fresh,
+otherwise-empty isolated directory, so it saw all four every single time.
+`customModelInjection`'s `skipFirstRunPrompts` (`true` on claude's entry,
+requires `apiKeyTrustFile` since it reuses the same file) pre-seeds the
+state a real profile accumulates from answering all of that once:
+`hasCompletedOnboarding: true` and the launching session's own
+`projects[workingDir].hasTrustDialogAccepted: true` go into the same
+`<configDir>/.claude.json` the API-key approval above already merges into
+(other projects, and other fields on this session's own project entry, are
+left untouched), and `skipDangerousModePermissionPrompt: true` goes into
+`<configDir>/settings.json` — a different file, merged the same
+corrupt-tolerant way. `workingDir` is used exactly as the session was
+launched with as its cwd, never realpath'd or slash-normalized, since
+that's the literal string Claude Code itself uses as the project key.
+
+**llama-swap gets two more fixes on top of the context-length/config-dir
+ones above, both from watching a real switch live.** llama.cpp only ever
+runs one model at a time; llama-swap swaps the backing process on demand,
+which can take anywhere from a few seconds to well over a minute:
+
+- **The conflict check.** Both apply routes (the restart one here and the
+  one-shot `POST /api/quick-start` above) call llama-swap's own
+  `GET /running` first — feature-detected, so a plain llama.cpp/OpenAI-
+  compatible server (no such endpoint) is simply never checked. If a
+  _different_ model is currently loaded and ready, and another **live
+  session's own selection** is using it, the apply returns
+  `{requiresConfirmation: true, currentlyLoadedModel, affectedSessions}`
+  instead of silently switching — nothing is applied or created yet.
+  Retrying with `confirmedSwap: true` skips the check (the legacy `confirmed: true`
+  still means both questions). Switching with nothing
+  else affected proceeds immediately; this is a warning about disrupting
+  another session, never a gate on the switch itself.
+- **Actually starting the load.** llama-swap has no "switch model" admin
+  call — the only thing that starts a swap is a real inference request
+  naming the model, and confirmed live: applying a selection alone never
+  reached llama-swap at all (nothing in its own server logs), since nothing
+  had actually asked it to load anything yet. Both apply routes now also
+  send the smallest real request that will —
+  `POST <baseUrl>/v1/chat/completions` with `max_tokens: 1` and one
+  throwaway message — whenever the
+  target model isn't already the one loaded and ready, fire-and-forget (its
+  response is never read; `GET /api/model-endpoints/:id/running-status`,
+  polled client-side, is what actually confirms readiness). The response
+  also carries `modelSwapInProgress: true` in that case, which is what
+  drives the Run-menu picker's own "loading model" status banner.
+
+## Catching a swap after the fact
+
+The conflict check above only runs at the moment a session is created or a
+model is applied — it has no way to catch a swap that happens **later**.
+Confirmed live: a session created while nothing else conflicted at that
+exact instant can still get silently displaced afterward, once a
+_different_ session's own normal use (or its own create-time load trigger)
+asks llama-swap to load something else. llama-swap has no push
+notification of its own for this, so a background sweep
+(`detectCustomModelSwapDisplacements`, `CUSTOM_MODEL_SWAP_CHECK_INTERVAL_MS`
+= 20s in `server.ts`) polls `GET /running` once per distinct endpoint that
+has at least one live custom-model session, and compares each such
+session's own `modelId` against what is actually loaded. A session whose
+model is no longer in that list gets a `custom-model:swapped-out` SSE event
+(`{sessionId, sessionName, endpointId, previousModel, currentlyLoadedModel}`),
+shown as a global toast — global rather than tied to that session's tab,
+since the whole point is telling the user before they type into it
+expecting the model they picked. Notifies **once per displacement**: the
+same de-dupe `Set` clears a session's flag once its own model is loaded and
+ready again, so a later, genuinely new displacement notifies again rather
+than the session staying silently un-notified forever after the first one.
+
+## Context-window floor warning
+
+Claude Code's own fixed per-turn overhead (system prompt + tool schemas,
+empirically ~36.4K tokens) can exceed a small local model's _entire_ real
+context on its own, before any conversation history exists to fill it —
+confirmed live twice, both as an `in:0 out:0` failure on the very first
+message sent. `CLAUDE_CODE_MAX_CONTEXT_TOKENS` (above) cannot fix this: it
+only governs when Claude Code compacts conversation history, and there is
+no history yet on message one. Applying such a model would look like the
+endpoint being ignored, or the wrong model being used, when in fact the
+endpoint applied correctly and the model is simply too small for this CLI.
+
+Both apply routes (the restart route and the one-shot `POST
+/api/quick-start`) now check for this **before** launching or restarting
+anything, gated on the CLI's registry entry declaring a `contextLengthVar`
+(currently only claude — the check is a no-op for every other CLI by
+construction, never a hardcoded mode check). If the model's discovered
+context (`modelContextLengths`, from discovery above) is below
+`CLAUDE_MIN_SAFE_CONTEXT_TOKENS` (40000, comfortably above the measured
+~36.4K overhead), the response is `{requiresContextWarning: true, modelId,
+contextLength, minSafeContextTokens}` instead of applying — nothing is
+restarted or created yet. A context length that was never discovered at
+all skips the check entirely (nothing to compare, so it fails open rather
+than warning on every model an endpoint hasn't reported a size for).
+Retrying with `confirmedContext: true` launches anyway (the legacy `confirmed: true` still means both questions).
+
+The Run-menu picker shows this as an in-app modal
+(`#customModelContextWarningModal`, matching the llama-swap conflict
+modal's look) naming the model, its discovered context, and the safe
+floor, and explaining the fix: reconfigure llama-swap to give that model
+(or a smaller one) an explicit larger context instead of relying on
+auto-fit (`--fit-ctx`), which optimizes for the biggest _model_ that fits
+rather than the biggest _context_ — e.g. adding `-c 65536` (or as large a
+`--ctx-size` as the hardware holds) to that model's llama-swap config
+entry. A smaller model at a much larger explicit context often fits in
+the same VRAM a bigger model's auto-fit context gets shrunk to make room
+for.
+
+Clear back to the harness's native cloud default with:
+
+```bash
+curl -sk -X POST https://localhost:3000/api/sessions/<sessionId>/custom-model \
+  -H 'Content-Type: application/json' -d '{"clear": true}'
+```
+
+Clearing also removes the env vars the selection injected from the tmux
+session (they persist there and would otherwise be inherited by the
+relaunched CLI) and deletes the per-session config directory
+(`~/.codeman/custom-model-configs/<sessionId>`, written 0600 because pi and
+omp embed the API key in it). That directory is also removed when the
+session is deleted. The selection survives a Codeman restart: the endpoint
+id, model and injected key NAMES are persisted, the values are re-derived
+from the endpoint store on recovery, and the pane keeps running against the
+endpoint in between because tmux retains its environment.
+
+⚠️ Clearing removes injected keys **by name**, and `CLAUDE_CONFIG_DIR` is one
+of the names claude's selection injects — so a session that ALSO had
+`CLAUDE_CONFIG_DIR` set through the generic `envOverrides` field (the
+per-client-account case) loses that override on clear too, and silently
+falls back to the server's default Claude account. If you route a session
+to a specific account this way, re-apply the override after clearing a
+custom-model selection from it.
+
+**New sessions always default back to the harness's native backend.** A
+custom-endpoint selection is a per-session choice, never a sticky global
+default — starting a fresh session doesn't inherit whatever the last one was
+pointed at.
+
+## Confidence per harness
+
+Every harness except Antigravity has now been run end-to-end against a real
+llama-swap server via `scripts/test-local-llm-harnesses.ts` (a dynamic
+script that reads the live CLI registry, so a registry change is picked up
+automatically). Results:
+
+- **Claude, opencode, Pi, Grok, OMP** — verified: a real "hello world" reply
+  came back through the endpoint.
+- **Codex** — the config is structurally correct, and against a llama-swap
+  server that DOES answer `/v1/responses` (confirmed live: a plain,
+  no-tool-call chat turn returned a real reply), the picture is more
+  nuanced than a flat failure. A real tool-call attempt (`run the shell
+command: echo hello`) came back as `agent_message` TEXT — literally the
+  tool-call JSON printed as the model's answer — instead of a
+  `function_call` item Codex would actually execute (confirmed via `codex
+exec --json`'s raw event stream). So plain chat can work while the thing
+  that makes Codex a coding agent — actually running commands and editing
+  files — does not; treat Codex as still unreliable for real work against a
+  llama.cpp/llama-swap endpoint, tool-calling gap included, not just the
+  earlier-documented `wire_api` mismatch (which not every deployment hits
+  the same way — some legitimately have no `/v1/responses` route at all).
+  Separately, EVERY custom-endpoint Codex session prints `Model metadata
+for '<id>' not found. Defaulting to fallback metadata...` on launch —
+  confirmed harmless (the reply above still came back correctly): Codex's
+  model metadata (reasoning-tier options, per-model system-prompt
+  templates, context-window figures) comes from `models_cache.json`, a
+  local cache of OpenAI's own hosted model catalog that a custom local
+  model can never appear in by construction, since it isn't one of
+  OpenAI's models. There's no config.toml override for a model's metadata,
+  and fabricating a fake catalog entry would mean copying the _shape_ of
+  OpenAI's own proprietary schema (their per-model system-prompt content
+  included) for a warning that doesn't otherwise affect behavior — not
+  something to build into discovery.
+- **Gemini** — fails with `Invalid auth method selected`, traced to an
+  undocumented `GATEWAY` auth path gemini-cli selects once
+  `GOOGLE_GEMINI_BASE_URL` is set. Unresolved after real investigation
+  (several auth workarounds were tried and ruled out); do not rely on
+  Gemini support yet.
+- **DeepSeek** — root cause of the `HTTP_404` found and fixed. DeepSeek
+  Harness's own bundled provider module (`@deepseek-ai/dsh-llm-deepseek`)
+  builds its request URL as `${DEEPSEEK_BASE_URL}/chat/completions` with no
+  `/v1` insertion of its own (its real public API, `https://api.deepseek.com`,
+  expects the caller's base URL to already carry any needed prefix) —
+  confirmed by reading its own source and, live, that
+  `POST <baseUrl>/chat/completions` 404s against llama-swap while
+  `POST <baseUrl>/v1/chat/completions` succeeds; the harness's own error
+  template (`DeepSeek API error (HTTP ${status})`) matches the originally
+  reported symptom exactly. `customModelInjection`'s new `appendV1Suffix`
+  (deepseek's entry only — claude/gemini must NOT get it, since claude was
+  already confirmed working against the raw `baseUrl`) fixes it by writing
+  `DEEPSEEK_BASE_URL` with `/v1` appended. Not yet re-run end-to-end with a
+  real `dsh` binary (no install available in this environment) — the fix
+  is source-confirmed and live-verified at the HTTP level, but a real
+  "hello world" reply through `dsh` itself is still outstanding before
+  calling this fully verified like the harnesses above.
+- **Antigravity** — no known custom-endpoint mechanism at all; unsupported.
+
+See the confidence table in `custom-model-endpoints-plan.md` for the full detail behind
+each result. `scripts/test-local-llm-harnesses.ts` is the standalone script
+used to check a harness against a real endpoint outside the web UI
+entirely; see its own `--help` for usage.
+
+## Security note
+
+Every env var this feature can set that redirects a session's traffic
+(`ANTHROPIC_BASE_URL`, `GOOGLE_GEMINI_BASE_URL`, `CODEX_HOME`, etc.) is
+listed in that CLI's `privilegedEnvKeys` in the CLI registry, so a
+non-granted multi-user owner cannot set one directly via the generic
+`envOverrides` API field — only through this feature's own route, which
+computes the value from an admin-configured, SSRF-guarded endpoint rather
+than trusting arbitrary client input. See the "Multi-user security
+hardening" section of `custom-model-endpoints-plan.md` for the full reasoning; several
+of these were reachable via the generic `envOverrides` field even before
+this feature existed, and building this surfaced and closed that gap.

docs/deepseek-integration-plan.md

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

docs/deepseek-integration.md

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

docs/docker-cases.md

@@ -2,7 +2,7 @@
 
 Run a case inside an **isolated Docker container** instead of directly on the host. Any number of Codeman sessions can share one container (it is scoped to the case, not the session), so a whole project lives in a sandbox with its own network, resource caps, and filesystem, and you can **export the container to move it to another machine**.
 
-Docker mode is a **location overlay on cases**, the direct analog of [remote SSH cases](./remote-hosts.md): where a remote case runs a local tmux pane doing `ssh host` into a durable remote tmux server, a docker case runs a local tmux pane doing `docker exec -it` into a durable **in-container** tmux server. It is not a separate `SessionMode`, so `claude` / `shell` / `opencode` / `codex` / `gemini` all work inside the container.
+Docker mode is a **location overlay on cases**, the direct analog of [remote SSH cases](./remote-hosts.md): where a remote case runs a local tmux pane doing `ssh host` into a durable remote tmux server, a docker case runs a local tmux pane doing `docker exec -it` into a durable **in-container** tmux server. It is not a separate `SessionMode`, so `claude` / `shell` / `opencode` / `codex` / `gemini` / `antigravity` / `pi` / `grok` / `deepseek` / `omp` all work inside the container.
 
 ## One-time setup: build the base image
 
@@ -15,6 +15,76 @@ node scripts/build-agent-image.mjs          # builds codeman/agent:base
 
 The image is **secret-free**: credentials are delivered at runtime (bind mounts or `docker exec --env`), never baked in, so exports never leak them.
 
+⚠️ **Re-build with `--no-cache`, always.** The CLIs are installed in a single `RUN npm install -g` layer, so a plain rebuild re-uses it from the Docker layer cache and the CLIs stay frozen at whatever versions the image was **first** built with, however long ago that was. Editing the Dockerfile does not help unless the edit lands at or above that line: a change appended below it leaves the npm layer cached and only runs the new step. Observed 2026-08-06: a rebuild silently kept a stale `@openai/codex@0.144.6` whose aliased platform binary had not installed, so every `codex` docker case died with `Missing optional dependency @openai/codex-linux-x64` while the build itself reported success.
+
+```bash
+node scripts/build-agent-image.mjs --no-cache
+```
+
+### Which CLIs the image contains
+
+The npm-published CLIs come from `ARG CLI_NPM_PACKAGES`, which `scripts/build-agent-image.mjs`
+fills from `config/clis.stock.json` (generated from `src/config/cli-registry/stock.ts`). Adding
+a stock CLI that installs with a plain `npm install -g` needs no Dockerfile edit. The ARG
+defaults to the same list in the same order, so a bare `docker build` produces a byte-identical
+layer — a different order would be a different `RUN` string and so a needless cache miss.
+
+⚠️ It reads the **stock** catalogue, never the merged registry. A user's `~/.codeman/clis.json`
+must not change what is inside an image tagged `codeman/agent:base`, or two machines holding
+that tag hold different images and every cache decision downstream is a lie. Each entry's
+`enabled` flag IS honoured, so a CLI that ships disabled is never baked in.
+
+Five CLIs keep hand-written layers, for two different reasons that are easy to conflate.
+`antigravity`, `grok` and `omp` declare no `npmPackage` at all, so they never enter the shared
+npm layer and each gets a vendor-installer layer instead. `pi` and `deepseek` ARE on npm but
+carry `discovery.install.agentImageLayer` in `stock.ts` (a REGISTRY field, rather than an
+id-keyed table duplicated between the two producers of the image's build args), which pulls
+them out of the shared layer because a plain `npm install -g` is not enough for them:
+
+| CLI | Why it is not in the shared npm layer |
+| ------------- | ------------------------------------------------------------------------------------- |
+| `pi` | Installs with `--ignore-scripts`, kept in its own layer so the flag cannot leak to the others. |
+| `deepseek` | Needs `pnpm` alongside it (`dsh plugin`, issue #352) plus a `dsh-tui` profile install. |
+| `antigravity` | Not on npm — Google ships a standalone binary (~190MB, the largest layer). |
+| `grok`, `omp` | Not on npm — standalone vendor installers. |
+
+`test/docker-agent-image-coverage.test.ts` requires every special case to carry a written
+reason AND still be present in the Dockerfile, so an exclusion cannot silently become an
+omission — which is the same failure upstream `b6d0f1fa` hit in `install.sh`.
+
+Two things build this image: `scripts/build-agent-image.mjs` (a human) and
+`ensureAgentBaseImage()` in `src/docker-hosts.ts` (the app, on the first Docker case). They
+assemble the argv independently, because a `.mjs` cannot import TypeScript, so
+`test/agent-image-build-args-parity.test.ts` pins them together. Without it, an image built by
+hand and one built by the app could hold different CLIs under the same tag.
+
+A zero exit code only proves the layers ran, not that the toolchain works. Verify by actually executing each CLI in the image, and check the build log for `Using cache` lines:
+
+```bash
+docker run --rm codeman/agent:base bash -lc \
+  'for c in claude codex gemini opencode agy pi grok dsh omp; do printf "%-9s " $c; $c --version 2>&1 | head -1; done'
+```
+
+⚠️ `dsh --version` is the one line above that answers a different question than the
+others: `dsh` is a profile launcher, so a working binary says nothing about whether
+the image can actually run a DeepSeek session. Check the profile the Dockerfile
+installs into the agent's HOME as well, or a `mode: 'deepseek'` case starts a pane
+that dies on arrival:
+
+```bash
+docker run --rm codeman/agent:base ls ~/.dsh/profiles/dsh-tui/package.json
+```
+
+Building that profile is also why `pnpm` is in the image: `dsh plugin` forwards straight to a literal `pnpm` and exits 127 without it (issue #352), and pnpm — unlike npm — blocks dependency lifecycle scripts by default and fails the install over it, so the profile step passes `--config.dangerouslyAllowAllBuilds=true`.
+
+Antigravity (`agy`) and Grok (`grok`) are the two CLIs not installed from npm (Google and xAI ship standalone binaries), so each has its own Dockerfile step, adding roughly 190MB and 160MB respectively. Pi also gets its own step, because upstream documents installing it with `--ignore-scripts` and that flag must not silently change how the other npm CLIs install.
+
+Pi's credentials are seeded per-FILE rather than as a whole directory (`auth.json`, `settings.json`, `trust.json`, `models.json`, `models-store.json` out of `~/.pi/agent`), because that directory also holds `sessions/`, `extensions/`, `skills/` and the installed package trees — gigabytes on an active host. Consequence: in-container pi sessions are invisible host-side, so `pi -c` inside a Docker case only sees that container's own history. See [`pi-integration.md`](./pi-integration.md). Grok is seeded per-file for the same reason (`auth.json`, `config.toml`, `pager.toml` out of `~/.grok`, which also holds `sessions/`, `memory/` and the ~160MB binary under `downloads/`), with the same consequence for `grok -c`. See [`grok-integration.md`](./grok-integration.md). OMP is the one CLI in this family where `sessions/` is the EXCEPTION rather than the rule: `~/.omp/agent/{config.yml,mcp.json,models.yml,settings.yml}` are seeded per-file (the dir also holds SQLite caches and `terminal-sessions/`), but `~/.omp/agent/sessions/` is shared RW like codex's, not seeded, because Codeman reads it host-side for history recovery and `--resume` pinning. See [`omp-integration.md`](./omp-integration.md).
+
+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.
+
+Set `CODEMAN_AGENT_IMAGE_GIT_USER_NAME` and `CODEMAN_AGENT_IMAGE_GIT_USER_EMAIL` together to configure the agent image's Git identity. Rebuild an existing `codeman/agent:base` with `node scripts/build-agent-image.mjs --no-cache`, then recreate Docker-case containers so they use the rebuilt image.
+
 ## 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.
@@ -49,6 +119,49 @@ curl -X POST localhost:3000/api/cases/docker-link -d '{"name":"sandbox","hostId"
 curl -X POST localhost:3000/api/quick-start -d '{"caseName":"sandbox","mode":"claude"}'
 ```
 
+## Attach to a container you already run
+
+The tab's **Attach to an existing container** toggle points a case at a container **you**
+built and run. Codeman only ever `docker exec`s into it: it never creates, starts, stops,
+restarts or removes it, and it seeds no credentials into it, so the CLIs inside must already
+be installed and logged in. A missing or stopped container is an error to report, not a state
+to fix — start it yourself and reopen the session.
+
+- **Container Name** is a picker over the engine's containers that you can also type into
+  (the engine may be remote, or the container may not exist yet when you fill the form).
+  Stopped containers are listed too, sorted last and labelled, so "mine isn't here" is never
+  a dead end.
+- **Container Workdir** is a path that must already exist **inside** the container. Adoption
+  mounts nothing, so it need not match the host workspace path; **Browse** lists directories
+  inside the container itself. Without this check, a wrong path fails at launch as a bare
+  `execvp failed` inside the pane.
+- **Workspace Path** is still a real host directory. It backs file previews, attachments and
+  watchers exactly as it does for an owned case, but here it is only a mirror: nothing is
+  bind-mounted, so point it at whatever host directory your container already exposes.
+- **Check container** runs a read-only preflight and reports what is inside before you commit
+  to a case name (running or not, tmux present, which CLIs resolved).
+- **Run modes come from the container**, not the host: a host with no `claude` still offers
+  Claude if the container ships it, and a mode the container lacks is hidden.
+- Claude is launched **without** `--dangerously-skip-permissions` when the container's exec
+  user is root, because Claude Code refuses that flag as root and the refusal is only visible
+  inside the container.
+- Image, network and resource settings disappear from the form: they describe a
+  `docker create` that adoption never runs.
+
+Recreate is refused for an adopted case, full-image export is refused (it would commit a
+container that is not ours), unlinking the case leaves the container running, and the boot
+reaper skips it. Workspace-only export still works and never pauses the container.
+
+Equivalent API:
+
+```bash
+curl -X POST localhost:3000/api/docker-cases/adopt-preflight -d '{"hostId":"local","container":"my-dev-box","containerWorkdir":"/workspace"}'
+curl -X POST localhost:3000/api/cases/docker-adopt -d '{"name":"devbox","hostId":"local","container":"my-dev-box","hostWorkspacePath":"/home/you/projects/devbox","containerWorkdir":"/workspace"}'
+```
+
+In multi-user mode adoption is **admin-only**, unlike `docker-link`: an adopted container's
+mounts belong to whoever built it, so one mounting `/` would hand the adopter the whole host.
+
 ## Lifecycle
 
 - **Reconnect after a Codeman restart** lands back in the same live agent (the in-container tmux survives).

docs/docker-compose.md

@@ -0,0 +1,84 @@
+# Docker Compose deployment
+
+This configuration builds the Codeman application image locally from this checkout. It does not download or depend on a pre-built Codeman image.
+
+For the Compose configuration, environment settings, storage migration, and macvlan networking examples, see the [Docker deployment guide](../docker/README.md).
+
+The image includes Claude Code, Codex, Gemini CLI, and OpenCode. Authenticate a CLI from its Codeman session; credentials are never baked into the image.
+
+CLIs installed from **App Settings → Agents & CLIs → CLI management** (DeepSeek Harness, Pi, and the other npm-based ones) go to `~/.local` on the `CODEMAN_APPDATA_PATH` mount, so they survive an image rebuild and a container recreate. Releases up to 1.33.1 installed them into the image instead, so a CLI installed from Settings on one of those has to be installed again once after the rebuild. The same applies to a hand-run `npm install -g` inside a session: it writes to the image prefix (`/opt/codeman-cli`) and is lost on the next rebuild, so use `npm install -g --prefix ~/.local <package>` instead.
+
+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
+- A reachable Docker daemon
+
+The application container mounts the Docker daemon socket so Codeman can create and manage its isolated Docker cases. Treat anyone who can administer this Compose project as having Docker-host-equivalent access.
+
+## Start
+
+Copy the environment template, set a strong password, and confirm `CODEMAN_APPDATA_PATH`. The example maps `/mnt/user/appdata/codeman` on the host to `/home/${CODEMAN_RUNTIME_USER}` in the container, preserving Codeman state and CLI credentials outside Docker-managed volumes.
+
+```sh
+cp docker/.env.example docker/.env
+```
+
+On PowerShell, use the following command instead.
+
+```powershell
+Copy-Item docker/.env.example docker/.env
+```
+
+On Linux, run the stack with the start script. It determines `PUID` and `PGID` from the owner of `CODEMAN_APPDATA_PATH`, and `DOCKER_SOCKET_GID` from the configured Docker socket, before invoking Compose. A root-owned application-data directory is rejected so the runtime account cannot become UID 0.
+
+```sh
+bash docker/Start-Codeman.sh
+```
+
+On other platforms, run Compose directly. `PUID` and `PGID` default to `1000:1000`; set them in `docker/.env` when the application-data directory has a different owner. Naming the file with `-f` disables Compose's own discovery of `docker/docker-compose.override.yml`, so add a second `-f` for it when you keep one (see `docker/README.md`, Local customisation).
+
+```sh
+docker compose --env-file docker/.env -f docker/docker-compose.yaml up --build -d
+```
+
+The container starts as root, corrects the ownership of a bind source the daemon had to create, and drops to `PUID:PGID` with `setpriv` before Codeman starts; the capabilities that needs are declared in `docker/docker-compose.yaml` and named by the entrypoint when a compose file written elsewhere lacks them.
+
+Open `http://localhost:3000` and sign in with the username and password from `docker/.env`.
+
+## Operations
+
+The local image is tagged `codeman:local` by default. Change `CODEMAN_IMAGE` in `docker/.env` if a different local tag suits your environment.
+
+```sh
+docker compose --env-file docker/.env -f docker/docker-compose.yaml logs -f codeman
+bash docker/Start-Codeman.sh
+docker compose --env-file docker/.env -f docker/docker-compose.yaml down
+```
+
+`CODEMAN_APPDATA_PATH` holds Codeman state and survives container recreation. Remove that host directory only when deliberately resetting the installation.
+
+`CODEMAN_CASES_PATH` must be an absolute path on the Docker host. Compose mounts it at the same path inside Codeman, so the host daemon can bind the managed workspace into isolated Docker cases. Do not set it to `/home/${CODEMAN_RUNTIME_USER}/codeman-cases`.
+
+Compose passes `CODEMAN_APPDATA_PATH` into Codeman as `CODEMAN_DOCKER_HOST_HOME`. Codeman uses that value to translate generated Docker seed, credential and hook-secret bind sources from the container's home path into paths visible to the host Docker daemon.
+
+If `docker info` reports `SwapLimit=false`, set `CODEMAN_DOCKER_DISABLE_SWAP_LIMIT=1`. Isolated cases retain their configured memory limit. Codeman omits the unsupported swap-limit option and filters only the daemon's exact swap-capability warning while retaining every other Docker create error.
+
+If that directory was created by an earlier root-running image, change its ownership to the configured `PUID:PGID` before starting this version. This preserves existing CLI credentials and session state while allowing the unprivileged runtime account to use them.
+
+## Updating
+
+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. 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.
+
+Full detail, including the fingerprint baseline and the troubleshooting table: [`docker-self-update.md`](docker-self-update.md).
+
+## Docker cases
+
+The default socket path is `/var/run/docker.sock`, which works with a standard Linux Docker Engine. The Bash start script detects its numeric group ID. When running Compose directly, set `DOCKER_SOCKET_GID`, for example using `stat -c '%g' /var/run/docker.sock`, so the unprivileged `CODEMAN_RUNTIME_USER` account can create Docker cases. Docker Desktop users should set `DOCKER_SOCKET` in `docker/.env` only when their Docker installation exposes a different compatible socket path.
+
+Codeman Docker cases are sibling containers on the host daemon, not children of the application container. The Compose configuration handles their workspace bind mount through `CODEMAN_CASES_PATH`; the `/home/${CODEMAN_RUNTIME_USER}` application-data mapping is for Codeman state and ordinary in-container sessions, not sibling-case workspaces.

docs/docker-self-update.md

@@ -0,0 +1,239 @@
+# Self-update in the Docker Compose deployment
+
+Codeman running as a container updates itself from **App Settings → Updates**, the
+same place and the same button as a bare-host install. This document explains how
+that works, what it deliberately refuses to do, and how to recover when it stops.
+
+The bare-host updater is documented in
+[`architecture-invariants.md#self-update`](architecture-invariants.md#self-update);
+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`                                |
+| 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 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
+
+The bare-host updater does `git checkout <tag> && npm install && npm run build`,
+then asks systemd or launchd to restart the service. Two of those assumptions are
+false in a container:
+
+1. **There is no init system.** A container's supervisor is the Docker daemon,
+   which acts on the container, not on processes inside it.
+2. **The image is immutable.** A `git pull` into the image's baked `/opt/codeman`
+   would land in the container's writable layer, survive `docker restart`, and be
+   silently discarded by the next `docker compose up`.
+
+Both are solved by configuration rather than by a second updater:
+
+- **The checkout is a host bind mount.** `docker-compose.yaml` mounts the repo
+  (the same directory used as the build context) over `/opt/codeman`, so the
+  updater's `git checkout` writes to the host filesystem and survives the
+  container being recreated.
+- **The restart is the server exiting.** `restart: unless-stopped` relaunches the
+  container whenever its main process ends, including on a clean exit — so the
+  updater's final step is to signal the server, and Docker starts it again on the
+  freshly built `dist/`.
+
+Everything else — the release-tag channel, the auto-stash, the atomic
+`update-status.json` the browser polls across the connection drop, the boot-time
+reconcile that flips `restarting` to `completed` — is the existing machinery,
+unchanged. The container path is a new `SupervisorKind`, not a new updater.
+
+## What the pieces are
+
+| Piece                                          | Role                                                                |
+| ---------------------------------------------- | ------------------------------------------------------------------- |
+| Repo bind mount at `/opt/codeman`              | Makes the pull persistent. Without it, self-update is unavailable.   |
+| `codeman-node-modules`, `codeman-dist` volumes | Container-owned build artefacts, layered over the bind mount.        |
+| `CODEMAN_IN_CONTAINER=1`                       | Tells `detectSupervisor()` to restart by exiting.                    |
+| `restart: unless-stopped`                      | Turns that exit into a restart. Verified before every update.        |
+| `CODEMAN_RESTART_BY_EXIT=1`                    | The Compose file's declaration of that policy, so the updater may exit even with no Docker socket. |
+| Toolchain + devDependencies in the image       | Lets `npm install` and `npm run build` run inside the container.     |
+| `docker-env-applied.json`                      | Fingerprint baseline, written by `Start-Codeman.sh` on every start.  |
+| `docker-build-source.json`                     | What HEAD/`package-lock.json` the build artefact volumes currently reflect. Written by both `Start-Codeman.sh` and this in-place update, so the two agree on whether those volumes are stale. |
+
+### Why build artefacts are in named volumes
+
+`node_modules` and `dist` are mounted as named volumes **on top of** the repo bind
+mount. Without that, an update's `npm install` would write into the host checkout,
+leaving container-compiled native modules (node-pty builds from source here) in a
+directory that may also be used to run Codeman natively, and leaving `git status`
+permanently noisy.
+
+Docker seeds an empty named volume from the image, so the first start inherits the
+image's already-built `node_modules` and `dist` and pays no bootstrap cost.
+`docker compose down -v` is the supported reset: the next start re-seeds them.
+
+That seeding-only-while-empty behaviour has a second, less obvious edge: it also
+means a plain `docker compose build` triggered from OUTSIDE the container (for
+example `Start-Codeman.sh`, after a `git pull` done by hand rather than through
+this in-app updater) produces a fresh image whose freshly-built `dist`/
+`node_modules` then sit unused behind the volumes' OLD content — the container
+comes back up looking unchanged. `Start-Codeman.sh` detects this by comparing the
+checkout's current HEAD and `package-lock.json` hash against `docker-build-source.json`,
+and clears just the affected volume(s) before its own `--build` if they moved.
+This in-place update writes that same file after a successful build precisely so
+that comparison does not fire on stale information: without it, the next plain
+`Start-Codeman.sh` run would see the HEAD this update just checked out, not
+recognise it as already accounted for, and wipe the volumes this update just
+correctly rebuilt right back to the OLDER image.
+
+### Why the runtime image carries a build toolchain
+
+`npm run build` is `tsc` plus `esbuild`, both devDependencies, so the image no
+longer runs `npm prune --omit=dev`. And `npm install` may rebuild node-pty, which
+ships no Linux prebuild, so `python3`, `make` and `g++` are installed as well.
+
+This is the real cost of in-place updates: a noticeably larger image than a
+runtime-only one. It buys an update that takes about a minute instead of a full
+image rebuild, and it is why `NODE_ENV=production` is paired with an explicit
+`npm install --include=dev` in the updater.
+
+## The environment gate
+
+An in-place update applies **code only**. A restarted container reuses its existing
+image and configuration, so a release that changes the environment cannot take
+effect that way — and would half-apply: new code against an old environment. The
+updater therefore checks the **target release's own files**, read straight out of
+git with `git show <tag>:<path>` before anything is checked out.
+
+### 1. `server.Dockerfile` changed, so the image must be rebuilt
+
+Compared by sha256 against the fingerprint `Start-Codeman.sh` recorded when the
+running container was built.
+
+### 2. `docker-compose.yaml` changed, so the container must be recreated
+
+Same mechanism. A restart cannot pick up a new mount, port or environment
+variable; only recreating the container can.
+
+### 3. `.env.example` gained keys your `.env` has no value for
+
+The check that matters most, because **Compose will not tell you**. An unset
+`${VAR}` interpolates to the empty string; Compose prints a warning to a terminal
+nobody is watching and starts anyway. A new required setting therefore arrives as
+a silently blank environment variable and misbehaves later, far from the cause.
+The updater names the missing keys instead.
+
+Commented-out lines in `.env.example` are deliberately *not* keys — that is how
+the file marks optional overrides such as `# PUID=1000`, and counting them would
+block updates on settings you are meant to leave alone.
+
+### 4. A restart policy that would not bring the container back
+
+Before signalling the server, the updater asks the Docker daemon for its own
+container's restart policy. If it is `no`, the update is refused: applying it
+would take Codeman down and leave no UI to recover from.
+
+If the policy cannot be read at all (no Docker socket mounted) the update is
+still allowed, but the final step changes: the server exits only when the
+Compose file declared `CODEMAN_RESTART_BY_EXIT=1` (the shipped one does, because
+it is the file that sets `restart: unless-stopped`) or the daemon confirmed an
+auto-restart policy. Otherwise the build completes and the panel asks you to
+restart the container by hand. A container started by plain `docker run` with no
+restart policy therefore gets a staged update, never an outage.
+
+### What the gate deliberately does not do
+
+Every unknown fails **open**:
+
+- A missing fingerprint baseline (a container started before this feature existed)
+  is not treated as a change, or those installs could never update at all.
+- An unreadable `.env`, an unreachable Docker socket, or a target tag whose files
+  cannot be read all yield "no blocker" rather than a refusal.
+
+The one place an unknown does NOT fail open is the kill itself: with neither the
+Compose declaration nor a daemon answer, the updater stages the build and asks
+for a manual restart rather than exiting a server nothing may bring back.
+
+The gate catches a specific, detectable class of mistake; it is not a last line of
+defence. It is also re-evaluated server-side on `POST /api/system/update`, so
+hiding the button in the UI is a courtesy rather than the control.
+
+## The one residual risk
+
+The gate is derived from the diff, so it cannot see a release that needs a newer
+environment **without changing any of those files** — for example, code that
+depends on newer agent-CLI behaviour.
+
+That is why the four global CLIs in `server.Dockerfile` are **pinned**. Unpinned,
+the versions a user ends up with are a function of when their image was built
+rather than of any commit, and in-app updates make rebuilds rarer, which makes
+that drift worse over time. Pinned, "this release needs a newer CLI" becomes a
+Dockerfile change, which check 1 already detects. Bump them deliberately, as part
+of a release.
+
+The complementary merge-side guard is `test/docker-compose-env-parity.test.ts`,
+which fails CI when a variable is added to `docker-compose.yaml` without an entry
+in `.env.example`, or the reverse.
+
+## Sequence of an in-place update
+
+1. **Check** — `GET /api/system/update/check` finds the latest release tag, fetches
+   that one ref so the gate can read the target's files, and returns any blockers.
+2. **Start** — `POST /api/system/update` re-evaluates the gate, writes `queued` to
+   `update-status.json`, stages `self-update.sh` outside the repo and runs it.
+3. **Apply** — stash if dirty, fetch the tag, check it out, `npm install
+   --include=dev`, `npm run build`. A failure at any step rolls back to the
+   previous commit, rebuilds it and reports `failed`; the server is never
+   restarted into a broken build.
+4. **Restart** — write the terminal `restarting` marker, then signal the server.
+   The container exits and Docker restarts it.
+5. **Reconcile** — the rebooted server compares its own version against the target
+   and flips the status to `completed` or `failed`. The browser, still polling,
+   picks that up.
+
+Step 4 kills the updater script along with the container — unlike the systemd
+path, it does not outlive the restart. That is safe only because the terminal
+marker is written first, which is why nothing may be appended after the kill.
+
+## Troubleshooting
+
+**"This install can't update itself (unknown)"** — the repo bind mount is missing,
+so the container is running the baked image copy. Check `CODEMAN_REPO_PATH` and
+confirm the mounted directory really contains `.git`.
+
+**The update fails immediately with a git ownership or permission error** — the
+mounted checkout belongs to a different user than the one Codeman runs as
+(`PUID`), so git refuses it as "dubious ownership". `Start-Codeman.sh` warns
+about this at start; fix it by chowning the checkout to the same account that
+owns `CODEMAN_APPDATA_PATH`.
+
+**A rebuild is reported as required every time** — the fingerprint baseline does
+not match the checkout. `Start-Codeman.sh` writes it on every start, so start
+through that script rather than a bare `docker compose up` after either file
+changes.
+
+**Codeman does not come back after an update** — the build succeeded, since the
+updater gates the restart on it, so read the container logs with `docker compose
+logs codeman`. To roll back, check out the previous tag in the host checkout and
+run `docker/Start-Codeman.sh`.
+
+**The update failed during `npm install`** — most likely a native rebuild with no
+toolchain, meaning the image predates the toolchain being added. Rebuild once from
+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. `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
+
+Set `CODEMAN_DISABLE_SELF_UPDATE=1` in `docker/.env` and pass it through in the
+compose file's `environment:` block. The Updates panel then reports that in-app
+updates are disabled, and the host-side script is the only way to update.

docs/extending-codeman.md

@@ -0,0 +1,437 @@
+# Extending Codeman
+
+Codeman has no plugin runtime, and that is a deliberate choice rather than a
+missing feature. A plugin runtime means running third-party code inside a process
+that spawns agents with your credentials, on a server people routinely expose
+over a tunnel or Tailscale. Codeman's security model is one of its reasons to
+exist, so it does not hand that away for an extension mechanism.
+
+Instead there are four seams that already work, from any language, with nothing
+installed:
+
+| You want to | Use | Runs where |
+| --- | --- | --- |
+| Show your own UI inside Codeman | [Web tabs](#seam-1-web-tabs) | Your own process, rendered as a tab |
+| React when an agent needs you | [SSE events](#seam-2-sse-events) | Anywhere that can hold an HTTP connection |
+| Drive Codeman from a script | [HTTP API](#seam-3-http-api-and-cli) or the `codeman` CLI | Anywhere |
+| React inside a Claude session | [Hooks](#seam-4-hooks) | The agent's own machine |
+
+Everything below is covered by the stability promise in
+[`versioning-policy.md`](versioning-policy.md): endpoint paths, the response
+envelope, `errorCode` values, and SSE event names are stable. Additive changes
+(new endpoints, new optional fields, new events) are non-breaking. Breaking
+changes ship under a new prefix (`/api/v2`).
+
+## Before you start
+
+**Base URL.** `http://127.0.0.1:3000` by default. Prefer the versioned prefix
+`/api/v1/...` for anything you publish; the unversioned `/api/...` is an alias.
+
+**Auth.** If `CODEMAN_PASSWORD` is set, send HTTP Basic on every request, or
+authenticate once and keep the `codeman_session` cookie. With no password set,
+Codeman is loopback-only and unauthenticated.
+
+```bash
+curl -u admin:$CODEMAN_PASSWORD http://127.0.0.1:3000/api/v1/sessions
+```
+
+**Envelope.** Every response is `{"success": true, "data": ...}` or
+`{"success": false, "error": "...", "errorCode": "..."}`. Check the HTTP status
+or `body.success`, then read `body.data`. The full `errorCode` to status mapping
+is in [`api-reference.md`](api-reference.md).
+
+⚠️ A few legacy GETs (`/api/away-digest` among them) return a bare-ish body with
+the payload at the top level rather than under `data`. Read defensively with
+`body.data ?? body`.
+
+⚠️ A `401` is not an envelope at all: auth is rejected in a request hook that
+replies with the bare string `Unauthorized`, so parsing it as JSON throws. Branch on
+the status code before you parse, or a missing password looks like a broken endpoint.
+
+**Already driving Codeman from an agent?** The README's
+[Programmatic Guide](../README.md#driving-codeman-from-an-agent--programmatic-guide)
+covers the in-session case: the `CODEMAN_MUX`, `CODEMAN_API_URL`,
+`CODEMAN_SESSION_ID` and `CODEMAN_HOOK_SECRET_FILE` variables that let a CLI
+running inside Codeman find the API and avoid acting on itself. This page is for
+code running *outside* a session.
+
+## Seam 1: Web tabs
+
+The highest-leverage seam. Any web app you can serve locally becomes a tab beside
+your agent sessions. You write a normal web page; Codeman handles embedding it.
+
+```bash
+curl -u admin:$PASS -X POST http://127.0.0.1:3000/api/v1/webviews \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"My Dashboard","url":"http://127.0.0.1:8787","icon":"📊"}'
+```
+
+Fields: `name` (1 to 60 chars), `url`, and optionally `icon` (a single glyph, max
+8 code units), `embedMode` (`proxy` by default, or `direct`), and `trusted`.
+
+Related endpoints: `GET /api/v1/webviews`, `PATCH /api/v1/webviews/:id`,
+`DELETE /api/v1/webviews/:id`, `POST /api/v1/webviews/probe` (reachability and
+framing check), `POST /api/v1/webviews/:id/open`.
+
+### Why it is proxied
+
+By default your page is served through Codeman's own origin at `/webview/:cap/*`
+rather than framed directly. A direct iframe fails three ways at once: production
+is HTTPS so `http://` targets are blocked as mixed content, many dashboards send
+`X-Frame-Options: DENY`, and Codeman's own `default-src 'self'` CSP blocks
+cross-origin frames. Proxying solves all three without weakening the CSP.
+
+### The two things that will confuse you
+
+A proxied frame is sandboxed and therefore **opaque-origin** unless you set
+`trusted: true`. Two consequences look like bugs in your own app:
+
+1. **Root-absolute URLs built at runtime** (`/assets/x.png` assembled in JS)
+   escape the injected `<base>` tag. Codeman injects a `runtimeUrlShim()` that
+   patches the common DOM sinks, but if you construct URLs in an unusual way,
+   prefer relative paths.
+2. **Same-host `fetch` and `XHR` are CORS-checked with `Origin: null`.** Codeman
+   handles this with `buildProxyCorsHeaders()`, and the proxy is exempt from the
+   global `OPTIONS` short-circuit. If you see "Failed to fetch" while the page
+   itself renders fine, this is the area to look at.
+
+⚠️ `trusted: true` opts out of the sandbox. A proxied page is served from
+Codeman's origin, so `allow-same-origin` lets it read the Codeman page and call
+the API that spawns agents. Only mark your own trusted code.
+
+## Seam 2: SSE events
+
+`GET /api/v1/events` is a Server-Sent Events stream. Each message is
+`event: <name>` plus `data: <json>`. There are 149 event names following a
+`domain:action` convention, registered in `src/web/sse-events.ts`.
+
+The ones most integrations want:
+
+| Event | Meaning |
+| --- | --- |
+| `session:created`, `session:deleted` | A session appeared or went away |
+| `session:idle` | The agent stopped working |
+| `session:completion` | A completion message was detected |
+| `session:exit`, `session:error` | The session ended or failed |
+| `hook:permission_prompt` | The agent is asking for permission |
+| `hook:idle_prompt`, `hook:stop` | The agent is waiting on you, or stopped |
+| `hook:task_completed`, `task:completed` | Work finished |
+| `subagent:discovered`, `subagent:completed` | Background agent lifecycle |
+| `mux:died` | A multiplexer session died unexpectedly |
+| `cron:runCreated`, `cron:runUpdated` | Scheduled job activity |
+
+### Filtering
+
+`?sessions=id1,id2` suppresses only the high-volume `session:terminal` stream for
+sessions you did not list. Lifecycle and metadata events are always delivered, so
+you cannot accidentally filter away the thing you are listening for.
+
+Pass `?clientId=<uuid>` to enable live filter updates through
+`POST /api/v1/events/subscribe` without reconnecting the stream.
+
+### Example: notify when any agent needs you
+
+```js
+const res = await fetch('http://127.0.0.1:3000/api/v1/events', {
+  headers: { Authorization: 'Basic ' + btoa(`admin:${process.env.CODEMAN_PASSWORD}`) },
+});
+const reader = res.body.getReader();
+const decoder = new TextDecoder();
+let buf = '';
+const WANTED = new Set(['hook:permission_prompt', 'hook:idle_prompt', 'session:idle']);
+
+for (;;) {
+  const { value, done } = await reader.read();
+  if (done) break;
+  buf += decoder.decode(value, { stream: true });
+  const frames = buf.split('\n\n');
+  buf = frames.pop() ?? '';
+  for (const frame of frames) {
+    const name = frame.match(/^event: (.+)$/m)?.[1];
+    const data = frame.match(/^data: (.+)$/m)?.[1];
+    if (name && WANTED.has(name)) notify(name, JSON.parse(data ?? '{}'));
+  }
+}
+```
+
+## Seam 3: HTTP API and CLI
+
+Around 200 handlers across 21 route files cover sessions, cases, files, cron,
+respawn, Ralph, the orchestrator, search, and admin. Each route module carries an
+`@fileoverview` describing its endpoints.
+
+If the caller is an agent running _inside_ a Codeman session, install the packaged
+agent skill instead of teaching it these calls by hand: `skills/codeman` in the repo
+(`npx skills add Ark0N/Codeman --skill codeman -g`, or `codeman skill install
+[--case <name>]`, or the synced `agentSkillEnabled` App Setting for automatic
+per-case injection on Claude session create). The skill carries the guard, the
+safety rules, and verified wait/orchestration recipes.
+
+The common ones:
+
+```bash
+# List sessions (live + persisted + transcript history, deduped)
+curl -u admin:$PASS http://127.0.0.1:3000/api/v1/sessions/unified
+
+# Create a session
+curl -u admin:$PASS -X POST http://127.0.0.1:3000/api/v1/sessions \
+  -H 'Content-Type: application/json' \
+  -d '{"workingDir":"/home/me/project","mode":"claude"}'
+
+# Send a prompt (single-line only, and it must end with \r: Enter is sent only
+# when the input contains a carriage return; without it the text sits on the
+# session's prompt unsubmitted)
+curl -u admin:$PASS -X POST http://127.0.0.1:3000/api/v1/sessions/$ID/input \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"run the tests\r","useMux":true}'
+```
+
+`POST .../input` also accepts `clientId` (stable per client, max 128 chars) and
+`seq` (monotonic per session). Send both and the server applies each pair
+at-most-once, so retrying after a dropped connection cannot type the prompt
+twice. Omit them entirely rather than sending `null`.
+
+It also accepts `wait` and `waitTimeout`, which hold the response open until the
+session finishes the turn you just started. `wait` is `true` (the default signal
+set) or a comma list of `idle,working,stop,blocked,exit`; the result comes back
+under `data.wait`. Sending them changes nothing for callers that do not: without
+`wait` the response is still `{"success": true, "data": {}}` and the write is still
+fire-and-forget. The two interact with `clientId` / `seq` in one way worth knowing:
+a **tagged duplicate** (a pair the server already applied) skips the write but still
+waits, answering from the session's current state rather than blocking for a
+transition that already happened. It reports `"delivered": false, "duplicate": true`.
+
+### Waiting instead of polling
+
+Three calls block until something happens: `GET /api/v1/sessions/:id/wait` (a
+lifecycle signal), `GET /api/v1/sessions/:id/wait-output` (a literal string in the
+output), and the `wait` field above. Full parameter and response tables are in
+[`api-reference.md`](api-reference.md#long-polling-agent-wait). Four things decide
+whether your integration works, and the last one is what actually bites:
+
+- **A timeout is a `200` with `wait.timedOut: true`**, not an error. Loop over short
+  waits rather than issuing one long one, because `tailscale serve` and cloudflared
+  both cut idle connections and a single 10-minute call is the pattern most likely
+  to die in the field.
+- **`wait.timeoutMs`** is the timeout after server-side clamping (600 s ceiling by
+  default). Read it rather than assuming you got what you asked for.
+- **`stop` and `blocked` only exist for `claude` sessions**, and on a `shell` session
+  even `idle` fires only once at startup, so send-and-wait there can only time out.
+  See the Gotchas below.
+
+⚠️ **There is no readiness signal, and skipping readiness is the failure that looks
+like success.** A session reports `idle` before its CLI has spawned, and a `claude`
+worker in a brand-new case comes up on the CLI's **trust dialog**, which has a ❯
+prompt of its own. Prompt it at that moment and the text lands in the dialog, the
+`\r` does not get past it, and the session's startup `idle` lands inside the wait
+window: the wait resolves on `idle` in a couple of seconds with `timedOut: false`,
+indistinguishable from a finished turn. Wait for the pid, then wait for the
+composer, answering the dialog only as the bounded fallback.
+
+⚠️ **Answering it is not "press Enter".** Claude Code 2.1.252 dropped the options'
+numbers, reversed them, and highlights `No, exit` by default, so a blind `\r` quits
+the CLI and the pane is dead seconds after the spawn. Read the `❯` marker off the
+rendered pane (`GET .../terminal?full=1`), send `ESC [ B` while it sits on `No, exit`,
+re-read, and confirm only once the marker is on `Yes, I trust this folder`. Codeman's
+own auto-accept (`trustDialogNextKey()` in `src/session-trust-dialog.ts`) does exactly
+this, inside a 90 s startup window and a 6-keystroke cap.
+
+A worked orchestration: start a worker, get it ready, prompt it, wait, clean up.
+
+```bash
+API="${CODEMAN_API_URL:-http://127.0.0.1:3000}"   # auto-set in-session, correct scheme included
+AUTH=(-u "admin:$CODEMAN_PASSWORD")     # omit entirely if no password is set
+CURL=(curl -sk "${AUTH[@]}")   # -k: harmless on http, required on --https installs (self-signed cert)
+
+# 1. Start a worker session (creates the case if it does not exist yet).
+#    The guard matters: a TLS or auth failure otherwise leaves SID empty and every
+#    later step "succeeds" against nothing.
+SID=$("${CURL[@]}" -X POST "$API/api/v1/quick-start" \
+  -H 'Content-Type: application/json' \
+  -d '{"caseName":"worker-1","mode":"claude"}' | jq -r '.data.sessionId')
+[ -n "$SID" ] && [ "$SID" != null ] || { echo "quick-start failed"; exit 1; }
+
+# 2. READINESS: composer marker first, trust dialog only as the bounded fallback.
+#    Skip this and step 3 reports a turn that never ran. Match single tokens only:
+#    TUI text can arrive without its spaces. Stage 1 is short on purpose (an
+#    already-trusted case matches in <1 s; a first-run case can never pass it and
+#    pays it in full).
+#    ⚠️ NEVER answer the dialog with a bare \r. Its highlighted option is `No, exit`
+#    (claude-cli 2.1.252), so a blind Enter quits the CLI; and the dialog text stays
+#    in the buffer for the life of the session, so a `from=buffer` probe for `trust`
+#    keeps matching long after it is gone. Read the CURRENT pane instead and steer.
+until [ "$("${CURL[@]}" "$API/api/v1/sessions/$SID" | jq '.data.pid')" != null ]
+do sleep 1; done
+R=$("${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
+      --data-urlencode 'match=bypass' --data-urlencode 'from=buffer' \
+      --data-urlencode 'timeout=5000')           # composer's status bar = ready
+if ! jq -e '.data.wait.matched' <<<"$R" >/dev/null; then
+  ESC=$(printf '\033')   # \x1b is GNU-sed only; this form also works on macOS
+  for _ in 1 2 3 4 5 6; do
+    # Which option the ❯ marker sits on, read off the CURRENT frame.
+    K=$("${CURL[@]}" -G "$API/api/v1/sessions/$SID/terminal" --data-urlencode 'full=1' \
+        | jq -r '.data.terminalBuffer // empty' \
+        | sed -e "s/$ESC\[[0-9;?]*[a-zA-Z]//g" -e "s/$ESC[()][AB0]//g" | tr -d ' \t' \
+        | grep -i '❯[0-9.]*\(yes,itrustthisfolder\|no,exit\)' | tail -1 \
+        | sed -e 's/.*[Yy]es,.*/confirm/' -e 's/.*[Nn]o,.*/move/')
+    [ -n "$K" ] || break                      # no dialog on screen: nothing to answer
+    [ "$K" = confirm ] && IN="\r" || IN="$ESC[B"
+    "${CURL[@]}" -X POST "$API/api/v1/sessions/$SID/input" \
+      -H 'Content-Type: application/json' \
+      -d "$(jq -nc --arg i "$IN" '{input:$i,useMux:true}')" >/dev/null
+    [ "$K" = confirm ] && break
+    sleep 1                                   # re-read: confirm the arrow landed
+  done
+  "${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
+    --data-urlencode 'match=bypass' --data-urlencode 'from=buffer' \
+    --data-urlencode 'timeout=45000' >/dev/null
+fi
+
+# 3. Send the prompt AND register the wait in one call, so the answer cannot be
+#    the previous turn's idle state. Single line only, ending in \r (otherwise
+#    Enter is never sent and this wait times out on a turn that never started).
+W=$("${CURL[@]}" -X POST "$API/api/v1/sessions/$SID/input" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"Run the test suite and summarize the failures\r","useMux":true,
+       "clientId":"orchestrator","seq":1,"wait":"stop,exit","waitTimeout":60000}' \
+  | jq -c '.data.wait')
+
+# 4. That first wait probably timed out (60 s). Keep going in SHORT waits.
+for _ in $(seq 1 30); do
+  [ "$(jq -r '.timedOut' <<<"$W")" = 'true' ] || break        # signal fired, or wait ended
+  W=$("${CURL[@]}" \
+    "$API/api/v1/sessions/$SID/wait?until=stop,exit&timeout=60000" | jq -c '.data.wait')
+done
+jq -r 'if .ended or .aborted then "worker is not running"
+       elif .timedOut then "still working after 30 waits"
+       else "signal: \(.signal)" end' <<<"$W"
+
+# 5. Read what it produced, then delete the session YOU created, by exact id.
+#    ⚠️ NOT /output: its textOutput is empty for every tmux-backed session.
+#    `tail` counts BYTES, and the payload is terminal data with ANSI in it.
+"${CURL[@]}" "$API/api/v1/sessions/$SID/terminal?tail=8000" | jq -r '.data.terminalBuffer'
+"${CURL[@]}" -X DELETE "$API/api/v1/sessions/$SID"
+```
+
+Waiting on a marker instead of a signal is the form that works in **every** mode,
+and the only one that works on a `shell` session:
+
+```bash
+# ⚠️ Split the marker so the typed line never contains it: your own keystrokes echo
+# into the output stream, so an unsplit marker matches before the command has run.
+# `from=buffer` also catches a marker that printed before the wait registered.
+N=$RANDOM
+"${CURL[@]}" -X POST "$API/api/v1/sessions/$SID/input" \
+  -H 'Content-Type: application/json' \
+  -d "{\"input\":\"M=DONE; npm test; echo \${M}_$N rc=\$?\r\",\"useMux\":true}"
+"${CURL[@]}" -G "$API/api/v1/sessions/$SID/wait-output" \
+  --data-urlencode "match=DONE_$N" --data-urlencode 'from=buffer' \
+  --data-urlencode 'timeout=60000' | jq '.data.wait'
+```
+
+For shell scripting, the `codeman` CLI is the same surface without the HTTP
+plumbing:
+
+```
+codeman session start|stop|list|logs     codeman task add|list|status|remove|clear
+codeman ralph start|stop|status|reset    codeman users add|passwd|list
+codeman status | list | attach <path>    codeman doctor
+```
+
+## Seam 4: Hooks
+
+Claude Code hooks post to `POST /api/v1/hook-event` from inside an agent session.
+Codeman installs its own hooks automatically, but the endpoint is open to yours.
+
+```json
+{ "event": "task_completed", "sessionId": "abc123", "data": { "any": "json" } }
+```
+
+`event` must be one of `permission_prompt`, `elicitation_dialog`, `idle_prompt`,
+`stop`, `teammate_idle`, `task_completed`. Each becomes the matching `hook:*` SSE
+event.
+
+⚠️ This endpoint skips Basic auth so hooks keep working, but when auth is active
+the loopback bypass requires the `X-Codeman-Hook-Secret` header
+(`~/.codeman/hook-secret`) unconditionally.
+
+## Gotchas
+
+Every one of these has cost somebody real time.
+
+- **CORS is localhost-only.** `Access-Control-Allow-Origin` is echoed only for
+  `localhost`, `127.0.0.1`, and `::1`. A browser app on any other origin cannot
+  call the API. Integrate server-side.
+- **A missing `Origin` header is allowed**, which is why curl, CLIs, and hooks
+  work. Cross-site origins are blocked by the CSRF guard.
+- **Reverse-proxy domains are rejected** by the anti-DNS-rebinding Host allowlist
+  unless added via `CODEMAN_ALLOWED_HOSTS=host,.suffix`.
+- **`null` is not `undefined`.** Request schemas use Zod `.optional()`, which
+  accepts `undefined` only. `JSON.stringify({ field: null })` keeps the null on
+  the wire and fails with `INVALID_INPUT`. Omit the key instead. This has caused
+  shipped bugs more than once.
+- **`text/plain` bodies stay raw.** Auto-parsing them as JSON enabled
+  simple-request CSRF, so it is deliberate. Send `application/json`.
+- **Prompts are single-line and must end with `\r`.** The server splits your text
+  and Enter into two separate tmux writes (Ink needs them apart), but it sends the
+  Enter **only when the input contains a carriage return**. Without it your text
+  sits on the prompt unsubmitted, which is the single most common "the wait
+  endpoints don't work" report: the wait runs its full timeout on a turn that never
+  started. Newlines inside the string are stripped rather than rejected, so
+  `"echo A\necho B\r"` runs the single joined command `echo Aecho B`: send one line
+  per call.
+- **`wait-output`'s `from=now` is not "printed after you asked".** tmux repaints
+  the visible screen on attach, on resize, and on any TUI redraw, and a repaint
+  arrives as ordinary output, so text already on screen can satisfy a fresh wait.
+  Observed live: a marker echoed a minute earlier matched instantly. Use a marker
+  unique to each call, and build it so the typed line never contains it (your own
+  keystrokes echo into the stream). Matching is a literal substring, so `regex=` is
+  rejected with a `400` rather than ignored.
+- **`wait-output` matches the normalized PTY stream, not the screen.** ANSI escape
+  sequences are stripped (the `ESC ( B` charset escape a bash prompt emits on every
+  line included), a partial escape at a chunk boundary is held back until its tail
+  arrives, and a match may straddle PTY chunks, so text you printed yourself
+  matches reliably (`printf STRAD; sleep 1; printf DLEQQ` is matchable as
+  `STRADDLEQQ`). What can still fail is TUI output: a full-screen TUI positions
+  words with cursor moves, so its text can reach the matcher **without spaces** and
+  a multi-word match is unreliable there. Match one short space-free token, ideally
+  one you printed yourself, and keep it out of the typed line (your own keystrokes
+  echo into the stream).
+- **`stop` and `blocked` never fire for `shell`, `opencode`, `codex`, `gemini`,
+  `antigravity` or `pi` sessions.** They come from Claude Code hooks, which no other mode
+  installs, so only `idle`, `working` and `exit` exist there. Asking for them
+  explicitly is a `400`; omitting `until` is safe, since the server drops them from
+  the default set and echoes what it actually waited on as `wait.until`. Even in
+  `claude` mode, a Docker case needs `CODEMAN_DOCKER_BRIDGE_HOOKS=1` for hooks to
+  reach the server at all, a remote-SSH case's hooks may never arrive, and a case
+  written by Codeman < 1.13.0 against an `--https` install carries hook curls
+  without `-k` that TLS-fail silently — a 1.13.0+ server rewrites them the next
+  time a session starts in that case.
+- **Unwrap the envelope** before reading fields. `data` is not the response body.
+
+## Publishing your integration
+
+There is no registry and no review queue. Add the GitHub topic
+**`codeman-integration`** to your public repository so others can find it, and
+link back to Codeman in your README.
+
+If a real ecosystem of these appears, a manifest format and an install command
+become worth building. Until then, these four seams are the contract, and they
+require nothing of you but HTTP.
+
+## What Codeman deliberately does not have
+
+- **No in-process plugin runtime.** See the reasoning at the top of this page.
+- **No build or startup hooks** for third-party code. Run your own process.
+- **No per-plugin config or state directories.** Manage your own files.
+- **No sandbox for integration code**, because Codeman never launches it. Your
+  integration is your own process, started by you, with your permissions,
+  talking HTTP.
+
+That last point is about integration code specifically, not about Codeman.
+Sandboxing lives on a different axis here: the thing worth isolating is the
+**agent**, and you isolate it per case with
+[Docker cases](docker-cases.md), which run the agent in a hardened container with
+a bind-mounted workspace and seeded (not shared) credentials. An integration that
+creates or drives a Docker-backed session inherits that isolation for free, since
+it is a property of the session rather than of the caller.

docs/file-viewer-edit-plan.md

@@ -0,0 +1,435 @@
+# File Viewer edit mode (issue #212)
+
+Plan only. No implementation yet.
+
+Goal: close the loop "agent writes a file, you review it in the viewer, tweak two lines, save, tell the
+agent to continue" without hopping into the terminal, with the phone as the primary target.
+
+Scope from the issue: an Edit toggle on text previews, a write endpoint that inherits the read path's
+confinement, text-only, edit-in-place (no create, no delete, no rename), no editing through the
+Docker/remote overlays.
+
+---
+
+## 1. What exists today
+
+**Read path (backend), all in `src/web/routes/file-routes.ts`:**
+
+| Route                                | Line   | Notes                                                              |
+| ------------------------------------ | ------ | ------------------------------------------------------------------ |
+| `GET /api/sessions/:id/files`        | `741`  | Tree scan of `session.workingDir`, hidden files off by default      |
+| `GET /api/sessions/:id/file-content` | `865`  | The text/preview classifier. `findSessionOrFail` + `validateSessionFilePath` |
+| `GET /api/sessions/:id/file-raw`     | `1018` | Bytes, 50MB cap                                                    |
+| `GET /api/sessions/:id/file-preview` | `1254` | DOCX/PPTX to PDF, everything else redirects to `file-raw`           |
+| `GET /api/download`                  | `1384` | The only read route that also runs `isSensitivePath()`              |
+
+`file-content` classification order (`file-routes.ts:881-1011`): extension buckets (image / video / audio /
+known-binary) return metadata only; otherwise the bytes are read, sniffed for a NUL in the first 8KB, and
+either reported as `type:'binary'` or decoded as UTF-8 and **truncated to `lines` (default 500, hard cap
+10000)**. Caps: `MAX_TEXT_FILE_SIZE` 10MB.
+
+Confinement is `validateSessionFilePath()` (`src/web/route-helpers.ts:67`): `resolve()` then `realpathSync()`
+then reject if the result is not under `workingDir`. Because it realpaths the *full* path, a symlink whose
+target escapes the workspace is already rejected. Ownership is `findSessionOrFail()` which runs
+`canAccessOwned()` (`route-helpers.ts:102`), a no-op outside multi-user mode.
+
+**Read path (frontend), `src/web/public/panels-ui.js`:**
+
+- `loadFileBrowser()` `2947`, `renderFileBrowserTree()` `2978`, click to `openFilePreview()` `3056`.
+- `openFilePreview(filePath, sessionId, attachmentId)` `3193`: attachment-id branch, then docx/pptx, pdf,
+  svg branches, then the generic `file-content` fetch at `3274` with **`&lines=500` hardcoded**, rendering
+  text as `<pre><code>${escapeHtml(...)}</code></pre>` at `3298` and stashing `this.filePreviewContent`.
+- `closeFilePreview()` `3308`, `copyFilePreviewContent()` `3751`.
+- Markup: `src/web/public/index.html:420-432` (`filePreviewOverlay` / `-Title` / `-Body` / `-Footer`, two
+  header buttons: copy and close).
+- CSS: `src/web/public/styles.css:9320-9430`. Overlay `z-index: 2000`, window `80vw/80vh`, capped
+  `900x700`. There are **no `.file-preview-*` rules in `mobile.css` at all**.
+
+**Reachability on phones.** The header File Viewer button is hidden below 430px
+(`mobile.css:482`, locked by `KNOWN_PHONE_HIDDEN` in `test/mobile-header-buttons-policy.test.ts`), so on a
+phone the preview overlay is reached through:
+
+1. an attachment card's **Preview** button (`panels-ui.js:3451`), which is exactly the "agent just wrote a
+   file" path the issue describes,
+2. the attachment-history drawer (`panels-ui.js:3709`),
+3. App Settings to Panels to **File Browser** (`showFileBrowser`, applied in `settings-ui.js:2202`; the
+   panel is mobile-styled at `mobile.css:1868`).
+
+So edit mode is reachable on a phone today via (1) and (2) without touching the header policy. Improving
+the entry point is listed as an open decision in section 10, not assumed.
+
+---
+
+## 2. Threat model, stated honestly
+
+Anyone who can call this API can already reach `POST /api/sessions/:id/input` and type an arbitrary prompt
+into an agent running with `--dangerously-skip-permissions`. A workspace-confined write endpoint therefore
+does not create a new privilege tier for an authenticated caller.
+
+What it *would* create if built carelessly is a **new host-write primitive reachable by path**, so the
+things this plan actually defends against are:
+
+1. **Path traversal / symlink escape** writing outside the workspace.
+2. **TOCTOU**: a path component that becomes a symlink between validation and write.
+3. **Cross-user writes** in multi-user mode (`canAccessOwned`).
+4. **Silent data loss**, which is the highest-probability real-world failure here and gets its own section.
+
+CSRF is already covered: `registerHostGuard()` (`src/web/middleware/auth.ts:555-578`) rejects any
+non-safe-method request whose `Origin` is cross-site. The webview-capability exemption at that gate is
+fenced to `GET`/`HEAD` for the Referer form (`auth.ts:161`) and to `/webview/:cap/*` paths for the path
+form, so a proxied dashboard cannot reach a new `PUT /api/...`. Using `PUT` + `application/json` also
+forces a preflight for any cross-origin attempt.
+
+---
+
+## 3. Backend design
+
+### 3.1 New policy module: `src/config/file-editing.ts`
+
+Pure, unit-testable, no IO (config lives in `src/config/`, no barrel, import the file directly).
+
+```ts
+export const MAX_EDITABLE_BYTES = 512 * 1024;      // content cap, both directions
+export const EDITABLE_EXTENSIONS: ReadonlySet<string>;  // ts,tsx,js,jsx,mjs,cjs,json,jsonc,md,mdx,txt,
+                                                        // css,scss,less,html,htm,xml,svg?,yml,yaml,toml,
+                                                        // ini,cfg,conf,env?,sh,bash,zsh,fish,py,rb,go,rs,
+                                                        // java,kt,swift,c,h,cpp,hpp,cs,php,sql,graphql,
+                                                        // proto,lua,pl,r,jl,tf,gradle,csv,tsv,log,diff,patch
+export const EDITABLE_BASENAMES: ReadonlySet<string>;   // Dockerfile, Makefile, LICENSE, .gitignore,
+                                                        // .prettierignore, .editorconfig, .nvmrc, ...
+export function isEditableFileName(fileName: string): boolean;
+export function isDeniedEditRelativePath(rel: string): boolean;  // `.git/` subtree
+export function detectEol(text: string): 'lf' | 'crlf';
+export function applyEol(text: string, eol: 'lf' | 'crlf'): string;
+```
+
+Decisions baked in:
+
+- **Allowlist, not blocklist**, per the issue and per the existing attachment-guard precedent.
+- `svg` and `env` are deliberately marked with `?` above: `svg` is served as an untrusted octet-stream on
+  the read side (`file-routes.ts:118`) so allowing an edit is defensible, but I recommend **excluding
+  both** in v1. `.env` files are matched by `isSensitivePath()` anyway and would be rejected downstream;
+  excluding them at the allowlist keeps a single obvious refusal.
+- `isDeniedEditRelativePath` blocks the `.git/` subtree: `.git/hooks/*` is code execution and a corrupt
+  index is unrecoverable-looking to a user who only wanted to fix a typo. Other dotfiles stay allowed but
+  are not reachable from the tree UI anyway (`showHidden=false`).
+
+### 3.2 Read-for-edit: extend the existing GET
+
+`GET /api/sessions/:id/file-content?path=<rel>&edit=1`
+
+When `edit=1`:
+
+- skip line truncation entirely (a truncated buffer must never become an edit buffer, see section 4.1),
+- enforce `MAX_EDITABLE_BYTES` instead of `MAX_TEXT_FILE_SIZE` and answer 413 over it (as a structured
+  throw with `statusCode: 413`, the `throwFilesystemPickerError` pattern, since the central errorCode-to-
+  status map has no 413 entry; see the error-mechanics note in 3.3),
+- run the editability gate (`isEditableFileName`, `isDeniedEditRelativePath`, `isSensitivePath`,
+  `isBlockedAttachmentPath`) and the content gate (NUL sniff plus UTF-8 round-trip, see 4.3),
+- return `{ content, size, mtimeMs, totalLines, truncated: false, extension, editable: true, hash, eol }`.
+  `hash` is `sha256` hex of the exact on-disk bytes.
+
+Non-`edit` responses gain **only** `editable: boolean` (additive, no shape change for existing consumers),
+which is all the UI needs to decide whether to show the Edit button. No `hash` on plain reads: the Edit
+action re-fetches with `edit=1` anyway (section 4.1), which is where the hash comes from, and hashing every
+casual 10MB preview would be pure waste.
+
+### 3.3 Write: `PUT /api/sessions/:id/file-content`
+
+Body (new `FileWriteSchema` in `src/web/schemas.ts`, Zod v4):
+
+```ts
+{ path: string, content: string, baseHash: string, eol?: 'lf'|'crlf', force?: boolean }
+```
+
+Registered with an explicit route option `{ bodyLimit: 4 * 1024 * 1024 }`. **Fastify's default `bodyLimit`
+is 1MB and this repo configures none**, and JSON escaping expands content: 2x for a file full of quotes or
+backslashes, up to 6x for control characters (each serialized as a `\uXXXX` escape), so 512KB of content
+can legitimately exceed 1MB on the wire; blowing the limit produces a raw `FST_ERR_CTP_BODY_TOO_LARGE`, not an `ApiResponse` envelope. Two
+related sizing notes: `z.string().max()` counts **UTF-16 code units, not bytes**, so the schema's `.max()`
+is only a coarse pre-filter and the real cap is an explicit `Buffer.byteLength(content, 'utf8')` check in
+the handler (step 7a below); and 4MB comfortably bounds the worst-case expansion of a 512KB file without
+inviting multi-MB bodies elsewhere.
+
+**Error mechanics** (matters for both prod behavior and testability): a handler that *returns* a
+`{success:false, errorCode}` envelope gets its HTTP status assigned centrally by the preSerialization hook
+in `server.ts` (`httpStatusForErrorCode()`, `src/types/api.ts`), but the route-test harness
+(`test/routes/_route-test-utils.ts`) installs only `installRouteErrorHandler`, **not** that hook, so
+returned envelopes surface as HTTP 200 in tests. The PUT handler should therefore use the same
+structured-**throw** pattern as the filesystem picker (`throwFilesystemPickerError`, `file-routes.ts:411`):
+thrown `{statusCode, body}` errors are rendered identically in prod and in the harness, and they allow the
+one status the code map cannot express (413). The error envelope itself is strictly
+`{success:false, error, errorCode}`, **it has no data arm**, so no error response may carry extra payload.
+
+Handler order (each step is a test case):
+
+1. `findSessionOrFail(ctx, id, req)` (live sessions only, matching the read route, and it carries the
+   multi-user ownership check).
+2. `parseBody(FileWriteSchema, req.body)`, then `Buffer.byteLength(content, 'utf8') <= MAX_EDITABLE_BYTES`
+   or 413 (the schema `.max()` alone cannot enforce a byte cap, see the sizing note above).
+3. `validateSessionFilePath(session.workingDir, path)` or 404 (do not distinguish "outside workspace" from
+   "missing", matching the read route).
+4. `isSensitivePath(resolvedPath) || isBlockedAttachmentPath(resolvedPath, guard.blockedTrees)` or 403.
+5. `isDeniedEditRelativePath(relativePath)` or 403.
+6. `isEditableFileName(basename(resolvedPath))` or 400.
+7. `stat`: must be `isFile()`, size within `MAX_EDITABLE_BYTES`, else 400/413. **No `O_CREAT` anywhere in
+   this handler**, which is what enforces edit-in-place.
+8. Read current bytes, compute `hash`, run the NUL sniff and the UTF-8 round-trip check, else 400.
+9. `hash !== baseHash && !force` gives **409 CONFLICT** (`ApiErrorCode.CONFLICT`, plain envelope; the error
+   arm carries no data, see the error-mechanics note). The client's conflict dialog gets fresh state by
+   re-fetching `edit=1`, which it needs for its Reload action anyway.
+10. Build the output buffer: `applyEol(content, eol ?? detected-from-original)`; re-check
+    `Buffer.byteLength` against the cap.
+11. Write atomically in the resolved parent directory:
+    `fs.open(<dir>/.<name>.codeman-tmp-<rand>, 'wx', stat.mode & 0o777)`, then `fchmod(stat.mode & 0o777)`
+    (open's mode argument is masked by the process umask, so the chmod is what actually preserves an
+    unusual mode), write, `fsync`, close, `fs.rename(tmp, resolvedPath)`, unlink the temp on any failure.
+12. Re-stat, return `{ success: true, data: { path, size, mtimeMs, hash, totalLines } }`.
+
+Why `O_EXCL` temp plus rename rather than truncate-in-place:
+
+- `wx` cannot follow a pre-existing symlink, which closes the TOCTOU window from step 3 to step 11 without
+  needing `O_NOFOLLOW` gymnastics.
+- `rename()` does not follow a symlink in the final component, so even if `resolvedPath` were swapped for a
+  symlink after validation, the symlink itself is replaced and the swap target is untouched.
+- A crash mid-write leaves the original intact.
+
+Caveat to document in the code comment: rename replaces the inode, so hardlinks to the file keep the old
+content. That is the same trade-off vim makes by default and is preferable to a truncate window here.
+
+No SSE event in v1. Nothing else in the app needs to know: `image-watcher.ts` only reacts to
+`.png/.jpg/.jpeg/.gif/.webp/.bmp/.svg/.pdf/.docx/.pptx` adds (`image-watcher.ts:23-25`), none of which are
+editable text, and the temp filename does not match either.
+
+---
+
+## 4. The five traps
+
+These are the parts that turn a "small write endpoint" into a bug report.
+
+### 4.1 Truncation (the data-loss trap)
+
+The frontend fetches `&lines=500` (`panels-ui.js:3274`). Saving that buffer back would **delete every line
+past 500**. Worse, the content hash of the full file would still match, so an optimistic-concurrency check
+cannot catch it.
+
+Mitigations, all three:
+
+- The Edit affordance is only offered when the loaded payload came from `edit=1` (which never truncates).
+  Tapping Edit on an already-rendered preview **re-fetches** with `edit=1` before swapping in the editor.
+- The read-for-edit path 413s above `MAX_EDITABLE_BYTES` rather than truncating, so "too big to edit here"
+  is an explicit refusal with a message, never a silent partial buffer.
+- A test asserts `edit=1` never returns `truncated: true`.
+
+### 4.2 Line endings
+
+A `<textarea>`'s `.value` normalizes to LF. Saving a CRLF file naively rewrites every line, producing a
+whole-file diff for a two-line change. So: the read returns the detected `eol`, the client echoes it back
+unchanged, and the server re-applies it. Mixed-EOL files use the dominant style, which is lossy for the
+minority lines; call that out in the response and accept it in v1.
+
+### 4.3 Encoding
+
+`buf.toString('utf-8')` on a latin-1 or otherwise non-UTF-8 file yields U+FFFD replacement characters, and
+writing that back **corrupts the file**. The check is a round-trip:
+`Buffer.from(decoded, 'utf8').equals(buf)`. If it fails, `editable: false` and the write is refused. This
+also catches binary content that the NUL sniff misses. A UTF-8 BOM survives because it round-trips as a
+leading U+FEFF; do not strip it.
+
+### 4.4 Concurrency with the agent
+
+The whole use case is editing a file the agent just wrote and may write again. `baseHash` plus 409 is the
+guard. Do not use mtime alone: agents rewrite files within a single filesystem timestamp tick, and an
+identical rewrite should not be reported as a conflict.
+
+### 4.5 Symlinks and TOCTOU
+
+Covered by `validateSessionFilePath` (escape) plus `wx` temp and `rename` (post-validation swap). One
+intentional allowance: a symlink whose target is *inside* the workspace is edited through to its target,
+because `validateSessionFilePath` returns the realpath. That matches what a user tapping the file expects.
+
+---
+
+## 5. Frontend design
+
+All in `panels-ui.js` (prettier-exempt, hand-formatted; match the surrounding style), `index.html`,
+`styles.css`, `mobile.css`.
+
+### 5.1 State
+
+```js
+filePreviewEdit = { active, sessionId, path, baseHash, eol, original, dirty }
+```
+
+Reset in `closeFilePreview()` and on every `openFilePreview()` entry.
+
+### 5.2 Markup (`index.html:420-432`)
+
+Add one header button (pencil, `btn-icon-sm`, `id="filePreviewEditBtn"`, hidden by default) next to the
+copy button, and an edit bar inside the footer region holding Save / Cancel / a dirty dot. Keep the
+existing footer text element; the edit bar is a sibling toggled by class so the read-mode footer is
+untouched.
+
+### 5.3 Behavior
+
+- `openFilePreview()` shows the Edit button only when the response has `editable: true` and the render took
+  the text branch. Attachment-id previews, media, binary, pdf, docx/pptx and svg all leave it hidden.
+- **Enter edit**: re-fetch with `edit=1`; on 413 or `editable:false`, toast the reason and stay in read
+  mode. This fetch must **parse the error envelope on non-ok responses**: the existing generic
+  `if (!res.ok) throw new Error('Failed to load file')` pattern (`panels-ui.js:3275`) would swallow the
+  specific "too large to edit here" message, since error envelopes arrive with real 4xx statuses in prod. On success replace the body with `<textarea class="file-preview-editor" spellcheck="false"
+  autocapitalize="off" autocorrect="off" autocomplete="off" wrap="off">` and assign `.value = content`
+  (never `innerHTML`, so no escaping question arises). Do **not** autofocus: on a phone that opens the
+  keyboard before the user has picked a line.
+- `input` sets `dirty` and enables Save.
+- **Save**: `PUT` with `baseHash`, `eol`, and `content`. On success update `baseHash`/`original` from the
+  response, leave edit mode, re-render the read view from the local editor value (the response carries
+  metadata only, not content), toast "Saved". On **409** offer `Reload (discard mine)` / `Overwrite`:
+  Reload re-fetches `edit=1` and replaces the buffer; Overwrite re-sends with `force: true`. The 409 body
+  itself carries no state (section 3.3, step 9).
+- **Cancel / close / Escape while dirty**: `confirm('Discard unsaved changes?')`, consistent with the
+  existing `window.confirm` usage in this codebase (`panels-ui.js:4323`, `app.js:4176`). Note the global
+  Escape handler (`app.js:999-1007`) closes other panels via `closeAllPanels()` but does not touch this
+  overlay today; if Escape-to-close is wired up as part of this work it must go through the same dirty
+  guard.
+- `copyFilePreviewContent()` copies the live editor value while editing.
+
+⚠️ Repo gotcha to respect at the fetch call: **Zod `.optional()` rejects `null`**. Build the body with
+`eol: eol ?? undefined` (or declare `.nullish()`), or the PUT fails `INVALID_INPUT`. This has shipped as a
+real bug twice.
+
+### 5.4 Mobile
+
+- **Sizing.** The window is `80vw/80vh` centered with no mobile override, so when the keyboard opens on iOS
+  the lower half sits behind it. Add a `@media (max-width: 430px)` block using
+  `height: var(--app-height, 100vh)`, full width, no border radius. `--app-height` is already maintained
+  against `visualViewport` by `KeyboardHandler.handleViewportResize()` (`mobile-handlers.js:283-317`), so
+  the editor tracks the keyboard for free.
+- **iOS zoom.** The editor font must be >= 16px on phones; there is an existing zoom-prevention block at
+  `mobile.css` under `@media (max-width: 768px)`. Verify it covers `textarea` and do not override it with a
+  smaller `rem` value.
+- **Accessory bar.** Focusing any input fires `KeyboardHandler.onKeyboardShow()`, which calls
+  `KeyboardAccessoryBar.show()` and refits/resizes the terminal (`mobile-handlers.js:407+`). The bar's keys
+  target the **terminal**, not the editor, so an Esc or clear-input tap while editing goes to the agent.
+  The overlay's `z-index: 2000` covers the bar's `51`, so it is not visible, but confirm it is not
+  interactive underneath and consider an explicit `KeyboardAccessoryBar.hide()` while the editor holds
+  focus. This is the item most likely to look "fine on desktop, wrong on the phone".
+- No header-policy change is needed (section 1), so
+  `test/mobile-header-buttons-policy.test.ts` stays untouched.
+
+### 5.5 i18n
+
+`i18n.js` already skips `textarea`, `pre`, `code` and `.file-preview-content` in its `SKIP_SELECTOR`
+(`i18n.js:20-38`), so file content is never translated. Add zh-CN entries for the new chrome: Edit, Save,
+Cancel, Unsaved changes, Discard unsaved changes?, File changed on disk, Reload, Overwrite, Saved,
+Too large to edit here.
+
+---
+
+## 6. Docker and remote cases
+
+Out of scope per the issue, and the current behavior already degrades correctly:
+
+- **Docker cases**: the workspace is a host directory bind-mounted at the same absolute path, so a host-side
+  write is visible in the container immediately. Edit mode works and needs nothing special. Worth one line
+  in the docs.
+- **Remote SSH cases**: `workingDir` is a path on the remote host, and the READ routes now
+  resolve it over ssh (`src/remote-files.ts`, same `buildSshConnectionArgs` discipline as the
+  launch path — #415). What stays unsupported is the WRITE side: an `edit=1` / `PUT` answers
+  `400` "editing is not supported for files in a remote (SSH) case", `editable` is always
+  `false`, office previews and generated thumbnails answer `400`, and no remote file is ever
+  copied to the server's disk. Do not attempt an SFTP write path.
+
+---
+
+## 7. Tests
+
+| File                                        | Kind        | Covers                                                                 |
+| ------------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| `test/file-editing-policy.test.ts`          | pure unit   | `isEditableFileName` (allow + deny + basenames), `isDeniedEditRelativePath`, `detectEol`/`applyEol` round-trip incl. mixed EOL, BOM preservation |
+| `test/routes/file-write-routes.test.ts`     | `app.inject` | The handler order in 3.3, against a **real temp dir** (do not `vi.mock('node:fs')` in this file; set `MockSession.workingDir`, `test/mocks/mock-session.ts:14`) |
+| extend `test/routes/file-routes.test.ts`    | `app.inject` | `edit=1` never truncates; `editable` present on the plain read          |
+
+Status-code caveat for all of these: the route-test harness does not install the server's preSerialization
+envelope hook, so a handler that *returns* an error envelope answers 200 in tests. The statuses below are
+only assertable because the plan has the handler **throw** structured errors (section 3.3, error
+mechanics), which `installRouteErrorHandler` renders identically in prod and in the harness.
+
+Route cases to assert explicitly:
+
+1. happy path writes the bytes and returns a new hash
+2. `../` and absolute paths give 404
+3. symlink pointing outside the workspace gives 404
+4. symlink pointing inside is written through to the target
+5. non-allowlisted extension gives 400
+6. `.git/config` gives 403
+7. a `.env` in the workspace gives 403 (sensitive-path)
+8. a file with a NUL byte gives 400
+9. a latin-1 file that fails the UTF-8 round-trip gives 400
+10. stale `baseHash` gives 409 (`CONFLICT` envelope, no data); `force:true` then succeeds
+11. over `MAX_EDITABLE_BYTES` gives 413
+12. a path that does not exist gives 404 and creates nothing (no `O_CREAT`)
+13. multi-user: `authUser: {role:'user'}` against another user's session gives 404 (pass `authUser` to
+    `createRouteTestHarness`, otherwise the synthetic admin makes the test pass vacuously)
+14. CRLF file edited and saved stays CRLF
+15. file mode is preserved across the temp-plus-rename
+
+Run with `npm test -- test/routes/file-write-routes.test.ts`, never bare `npm test`.
+
+**End-to-end verification before any deploy** (unit tests passing is not sufficient here):
+
+- `curl -sk https://localhost:3000/...` against a **throwaway** session created for the purpose, never
+  `w1`/`w2`/`w3`; delete it by exact id afterwards.
+- Playwright on a phone profile: open a preview, tap Edit, type with `page.keyboard.type()`, Save, then
+  assert the bytes on disk changed. Assert real state, not HTTP 200.
+
+---
+
+## 8. Docs and release
+
+- This plan lives at `docs/file-viewer-edit-plan.md`.
+- `docs/architecture-invariants.md`: new anchor `#file-viewer-edit-mode` covering the write confinement
+  chain, the truncation invariant, and why temp-plus-rename.
+- `CLAUDE.md`: one line under the **Filesystem path picker** neighborhood noting that the File Viewer now
+  has a **third** file surface and that it is the only one that writes, plus its confinement rules.
+  Remember `CLAUDE.md` is prettier-ignored on purpose.
+- `docs/api-reference.md`: the new `PUT` and the `edit=1` query.
+- Release: a normal COM applies (the 1.10.0 batch hold is over). This is a new user-facing feature plus an
+  additive API surface, so **COM minor** when it ships.
+
+Formatting note: `panels-ui.js`, `styles.css`, `mobile.css`, `index.html` are all in `.prettierignore` and
+are hand-formatted; new TypeScript (`src/config/file-editing.ts`, route + schema edits) is prettier-enforced
+and must pass `npm run format:check`.
+
+---
+
+## 9. Implementation order
+
+Each phase is independently reviewable and leaves the tree working.
+
+1. **Policy module + tests.** `src/config/file-editing.ts` and `test/file-editing-policy.test.ts`. Pure, no
+   route wiring. (Small.)
+2. **Read-for-edit.** `edit=1` (returning `hash`/`eol`) plus the additive `editable` flag on plain reads,
+   tests. Nothing consumes it yet. (Small.)
+3. **Write endpoint.** `FileWriteSchema`, `PUT` handler, `test/routes/file-write-routes.test.ts`. Fully
+   testable by curl before any UI exists. (Medium, the security-relevant part.)
+4. **Desktop UI.** Edit button, textarea swap, Save/Cancel, dirty guard, 409 flow. (Medium.)
+5. **Mobile pass.** `mobile.css` sizing against `--app-height`, font size, accessory-bar interaction,
+   real-device check. (Small but the part that decides whether the feature is actually usable.)
+6. **Docs, i18n strings, changeset.**
+
+---
+
+## 10. Open decisions
+
+1. **Editor widget.** Recommend a plain `<textarea>` for v1: zero dependencies, no CSP question, no bundle
+   growth, and it is the only thing guaranteed to behave with the iOS keyboard. CodeMirror-light with
+   syntax highlighting is a clean follow-up once the write path is proven. The issue allows either.
+2. **Phone entry point.** Edit mode is reachable on a phone through attachment cards and the history
+   drawer without changing anything. A dedicated toolbar or overview affordance for "browse this session's
+   files" would make it discoverable, but it is a separate UX change and would need a decision against the
+   deliberately minimal phone header policy. Recommend deferring it and revisiting after the feature ships.
+3. **`svg` editability.** Recommend excluded in v1 (it is deliberately treated as untrusted on the read
+   side). Easy to add later.
+4. **Create / delete / rename.** Explicitly out of scope per the issue. Note that keeping `O_CREAT` out of
+   the handler is what makes that a structural property rather than a convention.

docs/grok-integration-plan.md

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

docs/grok-integration.md

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

docs/installer-v2-plan.md

@@ -0,0 +1,380 @@
+# Installer v2: three questions, then a URL you can open on your phone (Plan)
+
+Status: **Phase 1 IMPLEMENTED (2026-09-20)**, phases 2 and 3 open. It builds on
+`docs/tailscale-installer-plan.md` (implemented 2026-08-04), which made Tailscale a
+guided option; this round makes it the thing the install ENDS on, and makes the whole
+installer shorter to sit through. Owner decisions taken before implementation: rename
+is opt-in and **defaults to no everywhere** (the machine name is used for other things);
+the URL keeps the node name unless asked; `codeman-<hostname>` is the suggested name;
+sub-path is the default for an occupied `:443`.
+
+Verification record for phase 1 (all on the maintainer's box, 2026-09-20):
+
+- `test/install-sh-invariants.test.ts` (28 tests, incl. the new Tailscale safety pins)
+  and the detection-parity test pass; `bash -n` passes.
+- Every new decision function driven with stubbed tailscale state under **bash 5.2 and
+  bash 3.2** (the `bash:3.2` container CI uses): flags, the launch default, the serve
+  shape for free / ours / occupied `:443` (all four answers plus the non-interactive
+  default), the three serve commands, the rename question (Enter keeps the name; `--yes`
+  and non-interactive never rename; `codeman-*` nodes are skipped; `--name` is
+  sanitized), `run_step` success/failure/stdin, the unit round-trip of
+  `CODEMAN_BASE_URL`/`CODEMAN_PORT`/an escaped password, and the done screen.
+- A full non-interactive install into a sandboxed `HOME` with `CODEMAN_TAILSCALE=1`:
+  preflight summary, kept the existing prod mapping (no serve mutation), clone 2 s,
+  `npm install` 18 s, build 23 s, symlink, done screen; `install.sh status` on a pty
+  renders the QR code. Nothing on the real system changed.
+- **Sub-path mode end to end over the real tailnet**: an isolated Codeman
+  (`CODEMAN_INSTANCE`, port 3999, `--base-url /codeman`) behind
+  `tailscale serve --https=8445 --set-path /codeman 3999` answered `/codeman/api/status`,
+  `/codeman/` (with `<base href="/codeman/">` and `__CODEMAN_BASE__="/codeman"`), the
+  hashed CSS/JS, `/codeman` without a slash, and the SSE stream; mapping and server
+  removed afterwards. **Correction to section 2**: serve STRIPS the mount prefix
+  before proxying (a direct `/codeman/api/status` on the server is 404 while the same
+  path through serve is 200). That is fine because Codeman's ingress tolerates
+  unprefixed requests; `--base-url` is needed for the URLs Codeman EMITS, not for
+  what it receives.
+- Not yet exercised on a fresh machine (unchanged from the previous plan): Tailscale
+  absent / logged out / HTTPS toggle off, the rename against a real node (the
+  off-rename-re-add order is implemented but only unit-driven), macOS, uninstall. The
+  Mac mini and a throwaway VM are the venues; see section 8.
+- **Review fixes (2026-09-21)**, from the two reviews on PR #460 (DeepSeek Harness, then
+  Claude): the done screen's Start line is composed from every non-default value
+  (`start_command_hint`, shared with the exec branch as `export_bind_env`), so "do not
+  start" under a sub-path or a custom port no longer prints a bare `codeman web`; the
+  `--lan`/`--tailscale`/env preset paths keep an existing password instead of rewriting
+  the unit open; `--password`/`--port` flip `RECONFIGURE` so they reach the unit;
+  `install.sh name` re-syncs the unit's base URL after a rename; the sudo keepalive is
+  ended before the `exec` into the foreground server; Ctrl+C in the HTTPS-toggle poll
+  skips Tailscale instead of killing the run; `uninstall` asks before removing a
+  LaunchDaemon it never wrote; a foreign LaunchDaemon gets a restart hint and the done
+  screen stops claiming the new build is running; the preflight summary reads the
+  Tailscale state without node; the LAN security notice uses the configured port; a
+  bare re-run ends on the done screen; a build failure after a rename names the
+  `install.sh tailscale` recovery; `TS_JOINED_HERE` is gone.
+
+Goal, in one sentence: a user runs the one-liner, answers at most three questions, walks
+away during the build, and comes back to `https://<name>.<tailnet>.ts.net` printed with a
+QR code, already answering, on every device in their tailnet. That is exactly the
+maintainer's own production setup (`tnode.tailf80371.ts.net` fronting `127.0.0.1:3000`),
+and the installer should produce it without the user knowing what `tailscale serve` is.
+
+## 1. Where the installer is today
+
+Facts from reading `install.sh` (2886 lines, 19 `prompt_yes_no` sites) and the live
+Tailscale state on the maintainer's box (tailscale 1.102.2, user-owned node, MagicDNS +
+HTTPS certs on, serve mapping `443 -> https+insecure://localhost:3000`).
+
+**The order is backwards for a human.** The flow is: detect -> ask about git -> ask about
+node -> ask about tmux -> ask about build tools -> AI CLI menu -> ask about cloudflared ->
+clone -> `npm install` -> build (minutes) -> **then** the network-access question -> the
+Tailscale sub-steps (install? login URL, sudo for operator, admin-console toggle loop) ->
+the launch menu (no default; a bare Enter re-prompts) -> tunnel-service question. A fresh
+Ubuntu server taking the Tailscale route answers roughly ten prompts plus two to four sudo
+password prompts, split around a multi-minute build. The user cannot walk away at any
+point, and the question that matters most (how do I reach it) comes last.
+
+**The Tailscale flow works but was never exercised on a fresh machine.** The previous
+plan's manual matrix still lists items 1-4, 7 and 10-12 (Tailscale absent, logged out,
+HTTPS toggle off, port 443 occupied, macOS, uninstall, phone PWA) as untested. The
+maintainer's own verification was the idempotent "kept as-is" path.
+
+**The URL is the machine's name, full stop.** `setup_tailscale_serve` derives it from
+`.Self.DNSName`, and nothing lets the user influence it. A second Codeman on the same
+tailnet is `macminis-mac-mini.tailf80371.ts.net`, which tells you nothing about Codeman.
+
+**Port 443 taken means give up or clobber.** If another app already owns the root of
+`:443`, the only offer is "replace it?" (default no), and declining falls back to
+local-only. Codeman already supports running under a sub-path (`--base-url`), and
+Tailscale serve supports mounting a path (`--set-path`), so there is a third answer nobody
+is offered.
+
+**The result is invisible afterwards.** Once the terminal scrolls away, nothing in the app
+or the CLI tells the user their Tailscale URL again. `codeman doctor` does not probe
+Tailscale; App Settings -> Remote access shows only the Cloudflare tunnel.
+
+**Two service writers exist.** `install.sh` carries its own plist/unit generator (~180
+lines) next to `codeman service install` (`src/service-installer.ts`). They agree on the
+job name by design, but the bash copy is the one that writes `CODEMAN_PASSWORD` into the
+unit, so they cannot simply be merged. Left as-is in this plan (see section 9).
+
+## 2. What Tailscale makes possible for the name (researched 2026-09-20)
+
+| Option | Resulting URL | What it needs | Side effects | Verdict |
+| ------ | ------------- | ------------- | ------------ | ------- |
+| **A. Node name** (today) | `https://tnode.tailf80371.ts.net` | `tailscale serve --bg 3000` | none | **Default.** Zero admin-console work, matches the maintainer's prod. |
+| **B. Rename the node** | `https://codeman-tnode.tailf80371.ts.net` | `tailscale set --hostname codeman-<host>` (operator or root) | Renames the machine tailnet-wide: ssh targets, other serve URLs, the admin console entry. Tailscale de-dups a clash as `-1`. The cert follows the new name. | **Opt-in, default NO everywhere** (owner decision 2026-09-20: the machine is used for other things, so a bare Enter never renames it). The proposal was YES when the installer itself had just joined the tailnet; rejected. |
+| **C. Tailscale Service** | `https://codeman.tailf80371.ts.net` | tailscale >= 1.86 on the host; the host must have a **tag-based identity** ("You cannot use a device authenticated with a user account as a Service host"); the service is defined in the admin console first; the host is then approved there (or via `autoApprovers.services`). Public beta since 2025-10-28, all plans. | Re-authenticating a personal machine as a tagged node changes its identity (SSH ACLs, user attribution). Known daemon quirk: approval is not picked up until `serve clear` + re-advertise (tailscale/tailscale#18821). | **Detect and hint only** in this round. The maintainer's own node has `Self.Tags: null`, so it could not host one without re-tagging. Worth a real flow once someone with a tagged fleet asks. |
+| **D. Sub-path** | `https://tnode.tailf80371.ts.net/codeman` | `tailscale serve --bg --set-path /codeman 3000` plus `--base-url /codeman` on the server | Codeman runs under a prefix. Hooks are unaffected (they hit the raw port with no prefix, which `rewriteUrl` already tolerates). Serve forwards the prefix unchanged, which is exactly the shape `--base-url` was built for. | **The answer when `:443` root is already taken.** Replaces today's replace-or-nothing prompt. |
+| **E. Second port** | `https://tnode.tailf80371.ts.net:8443` | `tailscale serve --bg --https=8443 3000` | Port in the URL; the beta-preview recipe already uses this. | Fallback when the user rejects D. |
+| Funnel (public internet) | `https://tnode.tailf80371.ts.net` from anywhere | `tailscale funnel` | Public exposure; different risk class. | **Out of scope**, as before. Docs only, with the password warning. |
+
+Sources: Tailscale Services docs (`tailscale.com/docs/features/tailscale-services`), the
+Services beta announcement (`tailscale.com/blog/services-beta`), machine names
+(`tailscale.com/kb/1098/machine-names`), the serve CLI reference
+(`tailscale.com/docs/reference/tailscale-cli/serve`), the macOS variants page
+(`tailscale.com/docs/concepts/macos-variants`), and `tailscale serve --help` on 1.102.2
+(which lists `--service`, `--set-path`, `--yes`, `advertise`, `get-config`/`set-config`).
+
+**Trap for option B (verify on the Mac mini before shipping):** the serve config is keyed
+by `host:port` using the DNS name at configuration time (`"Web": {"tnode.tailf80371.ts.net:443": ...}`
+in `serve status --json`). Renaming a node after serve is configured most likely orphans that
+entry: the handler lookup uses the current name and never matches the old key, and the only
+tool that removes a stale key is `serve reset`, which this installer must never run. So the
+order is **rename first, then configure serve** on a fresh install, and on a retrofit
+(`install.sh name`) **turn our mapping off, rename, wait for `.Self.DNSName` to change,
+re-add**.
+
+## 3. Target UX
+
+### 3.1 Three questions, then walk away
+
+```
+  Codeman installer
+
+  Found:      git, Node 22.14, tmux 3.4, build tools     Missing: nothing
+  AI CLIs:    Claude Code (~/.local/bin/claude)
+  Tailscale:  connected as tnode (tailf80371.ts.net)
+  Existing:   none
+
+  1/3  How should the dashboard be reachable?
+         1) Tailscale  https://tnode.tailf80371.ts.net  (recommended, already connected)
+         2) Any device on your network (0.0.0.0, password required)
+         3) This machine only (127.0.0.1)
+       Choose [1/2/3] (default 1):
+
+  2/3  Name this machine "codeman-tnode" on your tailnet? [y/N]
+       (only shown for option 1; default no, always)
+
+  3/3  Run Codeman as a background service that starts on boot? [Y/n]
+
+  Installing… this takes a few minutes. You can leave this running.
+    ✓ dependencies    ✓ clone    ✓ build (2m 41s)    ✓ service    ✓ tailscale serve
+```
+
+Rules that make this work:
+
+- **Every step that needs a human runs BEFORE the build.** The dependency consent, the
+  AI CLI menu, the Tailscale install consent, the `tailscale up` login URL, the operator
+  grant, and the tailnet HTTPS toggle all move into the question phase. The build, the
+  service, `tailscale serve` and the verification are unattended.
+- **One consent for all missing system packages.** "Install git, Node 22 and build tools
+  now? [Y/n]" replaces four separate prompts. Each package still runs its own
+  distro-specific installer.
+- **One sudo prompt.** When anything needs root (packages, the Tailscale installer,
+  `tailscale up`, the operator grant), the installer says so once, runs `sudo -v`, and keeps
+  the timestamp alive in a background loop until it exits. macOS needs no sudo for the
+  Tailscale GUI-app CLI and the pattern still holds for Homebrew packages.
+- **Service is the default.** Enter on the last question installs the service; "run in
+  this terminal" and "don't start" stay reachable by answering, and by flag.
+- **The cloudflared question is gone from the main flow.** It is optional, defaults to
+  no, and has an in-app toggle (App Settings -> Remote access). The done screen mentions it
+  only when `cloudflared` is already installed. The Linux tunnel-service prompt goes with it.
+- **The HTTPS-certificates toggle no longer asks "re-check now?"** The installer prints the
+  admin URL, opens it in a browser when one is available (`xdg-open` / `open`, never on a
+  headless box), and polls `tailscale status --json` every 5 s for up to 5 minutes. Ctrl+C or
+  the timeout falls back exactly as today.
+- **Progress, not silence.** `npm install` and `npm run build` run behind one line each
+  with elapsed time; their output goes to `~/.codeman/install.log` and is printed only on
+  failure, with the exact retry command.
+
+### 3.2 The done screen
+
+One block, the URL first, a QR code the phone can scan, and nothing the user does not need
+right now.
+
+```
+  ✓ Codeman 1.31.0 is running
+
+    Your tailnet:    https://codeman-tnode.tailf80371.ts.net    (HTTPS, any of your devices)
+    This machine:    http://localhost:3000
+
+    ▄▄▄▄▄▄▄ ▄ ▄▄  ▄▄▄▄▄▄▄
+    █ ▄▄▄ █ ▄▄▀ ▄ █ ▄▄▄ █      scan with your phone
+    █ ███ █ ███▀▀ █ ███ █
+    █▄▄▄▄▄█ █ ▄ █ █▄▄▄▄▄█
+
+    Manage   systemctl --user restart codeman-web  ·  journalctl --user -u codeman-web -f
+    Update   re-run the install line, or App Settings → System → Updates
+    Docs     https://github.com/Ark0N/Codeman/wiki
+
+  Security: Codeman binds 127.0.0.1. Tailscale authenticates every device before a
+  packet reaches it. Details: docs/security-architecture.md
+```
+
+The QR comes from the `qrcode` package Codeman already depends on
+(`node -e "require('qrcode').toString(url, {type:'terminal', small:true}, …)"` from
+`$INSTALL_DIR`, verified locally: 17 rows by 45 columns). Skipped when the terminal has no
+color support or fewer than 50 columns. The QR encodes the plain URL, not an auth token:
+the tailnet is the login.
+
+### 3.3 Express mode and flags
+
+Env vars stay (`CODEMAN_TAILSCALE=1`, `CODEMAN_HOST`, `CODEMAN_PASSWORD`,
+`CODEMAN_NONINTERACTIVE=1`, `CODEMAN_PORT`). Flags are added because they are
+discoverable from the one-liner and pipe through `bash -s --`:
+
+```bash
+curl -fsSL https://getcodeman.com/install | bash -s -- --tailscale --service
+curl -fsSL https://getcodeman.com/install | bash -s -- --lan --password 'x' --service
+curl -fsSL https://getcodeman.com/install | bash -s -- --local --run
+curl -fsSL https://getcodeman.com/install | bash -s -- --tailscale --name codeman-build --yes
+```
+
+| Flag | Meaning |
+| ---- | ------- |
+| `--tailscale` / `--lan` / `--local` | Answer 1/3 (same semantics as `CODEMAN_TAILSCALE=1`, `CODEMAN_HOST=0.0.0.0`, `CODEMAN_HOST=127.0.0.1`) |
+| `--name <n>` / `--no-rename` | Answer 2/3: rename the node to `<n>`, or never ask |
+| `--service` / `--run` / `--no-start` | Answer 3/3 |
+| `--yes` | Accept every default, still prompt for a login URL (a human must open it) |
+| `--password <p>` | Same as `CODEMAN_PASSWORD` |
+| `--port <n>` | Same as `CODEMAN_PORT`; the serve target follows it |
+
+`--yes` differs from `CODEMAN_NONINTERACTIVE=1`: it is the interactive user saying "I trust
+the defaults", so it may install software and may wait on a login URL. Non-interactive stays
+the CI contract and never installs Tailscale.
+
+## 4. The Tailscale flow, v2
+
+The state machine from the previous plan stays; these are the changes.
+
+1. **Preflight, before the build** (`tailscale_preflight`): installed? -> install
+   (Linux: official script; macOS: brew cask, else download link and wait). Logged in? ->
+   `tailscale up` with the URL printed prominently and a 5-minute poll. Operator (Linux):
+   grant once under the single sudo session. HTTPS certs: poll instead of ask (Ctrl+C
+   during the poll skips Tailscale for this run rather than ending the installer). The
+   rename default does not depend on whether this run performed the login (decided NO
+   everywhere), so nothing records it.
+2. **Name** (`tailscale_choose_name`, question 2/3): shown only on the Tailscale route.
+   Default `codeman-<oshostname>` sanitized to `[a-z0-9-]`, max 63. Applied with
+   `ts_cmd_serve set --hostname`, then poll `.Self.DNSName` until it carries the new name
+   (up to 60 s). Order matters: this runs before any serve mutation (section 2 trap).
+   Declining keeps the node name. On a re-run against a node already named `codeman-*`,
+   the question is skipped.
+3. **Serve, after the service is up** (`setup_tailscale_serve`): unchanged idempotent
+   "kept as-is" path first. When `:443` root belongs to another target, the new prompt is:
+
+   ```
+   tailscale serve already sends https://tnode.tailf80371.ts.net to port 8080.
+     1) Add Codeman under a path:  https://tnode.tailf80371.ts.net/codeman   (default)
+     2) Use another port:          https://tnode.tailf80371.ts.net:8443
+     3) Replace the existing mapping with Codeman
+     4) Skip Tailscale for now
+   ```
+
+   Option 1 writes `--base-url /codeman` into the service unit (it is a `WebLaunchOptions`
+   field already, and `buildWebArgs` carries it) and runs
+   `tailscale serve --bg --set-path /codeman <port>`. Option 2 runs `--https=8443`.
+   `detect_tailscale_serve_url` learns to recognize all three shapes (root, path, port) so
+   uninstall, the security notice and the re-run default keep working.
+4. **Warm the certificate.** Right after serve is configured, fire one background
+   `curl -sk https://<url>/api/status` so Let's Encrypt issuance overlaps the rest of the
+   install instead of adding 30 s to the verify step.
+5. **Verify** as today (200 or 401 on `/api/status`), with the path-aware URL.
+6. **Services hint** (option C): when `.Self.Tags` is non-empty and `serve --help`
+   lists `--service`, the done screen adds one line: "This is a tagged node, so it can also
+   host `https://codeman.<tailnet>.ts.net` as a Tailscale Service: see Remote Access in the
+   wiki." No flow, no prompt.
+7. **macOS**: the App Store and Standalone variants cannot run before login, so a
+   LaunchAgent plus serve only comes back after someone logs in. The done screen says so on
+   macOS. The Mac mini (`arbbot`, headless, system LaunchDaemon) is the reference for the
+   "headless Mac" caveat, and `install.sh` must keep refusing to replace a LaunchDaemon it
+   did not write (today it removes one; that is a bug for the Mac mini and is fixed here:
+   detect `UserName` in the daemon plist and leave it alone with a message).
+8. **Uninstall** additionally offers to restore the original node name when this installer
+   renamed it (the original is recorded in `~/.codeman/install.json`, the one marker file
+   this feature adds, because tailscaled does not remember previous names).
+9. **Subcommands**: `install.sh tailscale` (unchanged purpose, now runs the v2 flow),
+   `install.sh name [<n>]` (rename with the off/rename/re-add dance), `install.sh status`
+   (prints the done screen again, URL and QR included, for the "what was my URL" moment).
+
+## 5. In-app: the URL stays discoverable
+
+Small, read-only, and the first server-side code this feature has ever needed.
+
+- **`GET /api/system/remote-access`** returns
+  `{ tailscale: { installed, connected, dnsName, url, mode: 'root'|'path'|'port'|null } }`
+  by running `tailscale status --json` and `tailscale serve status --json` through
+  `execFile` with the existing exec timeout, cached 30 s, resolved through the same
+  `get_tailscale_path` search as the installer (PATH, then the macOS app bundle), and a
+  no-op under `VITEST` like every other IO probe. Never mutates serve config.
+- **App Settings -> Remote access** gains a **Tailscale** row above the Cloudflare toggle:
+  the URL as a copy chip, a QR button reusing `showTunnelQR`'s modal, and when nothing is
+  configured a one-line hint with `bash ~/.codeman/app/install.sh tailscale`. The welcome
+  screen's "open on your phone" affordance shows the same QR.
+- **`codeman doctor`** grows a `tailscale` entry under `other` in
+  `config/dependency-registry.ts`: installed, connected, serving Codeman (URL). Pure
+  engine, injectable probe host, like the existing rows.
+- No new SSE event, no settings key, no state.json change.
+
+## 6. Security posture
+
+Nothing widens. The bind stays loopback; the tailnet is the authentication boundary;
+`.ts.net` is already in `DEFAULT_TRUSTED_HOST_SUFFIXES`. New surfaces are read-only
+probes. `install.sh` still never runs `tailscale serve reset`, still touches only the
+mapping it created, and gains one more never: it never advertises a Tailscale Service or
+runs `tailscale funnel`. The sudo keep-alive loop is killed by the existing `cleanup` trap.
+The rename records the previous name locally and offers the reversal at uninstall.
+
+## 7. Implementation inventory
+
+| File | Change |
+| ---- | ------ |
+| `install.sh` | New `parse_flags`, `preflight_summary`, `ask_everything` (the three questions), `sudo_session`, `run_step` (spinner + log), `tailscale_preflight`, `tailscale_choose_name`, `tailscale_rename_node`, `print_done_screen`, `print_qr`, `status` subcommand, `name` subcommand. Modified: `main` (reordered into ask -> work -> done), `choose_network_binding` (question 1/3, same defaults), `setup_tailscale_serve` (path/port options), `detect_tailscale_serve_url` (three shapes), `setup_systemd_service`/`setup_launchd_service` (`--base-url`, LaunchDaemon guard), `uninstall` (rename reversal), header docs (flags). Removed from the main flow: the cloudflared prompt, the tunnel-service prompt. bash 3.2 rules unchanged. |
+| `src/web/routes/system-routes.ts` | `GET /api/system/remote-access` |
+| `src/tailscale-status.ts` (new) | Pure parser for the two JSON shapes + the IO wrapper; unit-tested against captured `serve status --json` fixtures (root, path, port, foreign target, none) |
+| `src/config/dependency-registry.ts`, `src/utils/dependency-checker.ts` | `tailscale` doctor row |
+| `src/web/public/index.html`, `settings-ui.js`, `panels-ui.js` | Tailscale row + QR, welcome-screen QR |
+| `test/install-sh-invariants.test.ts` | Extend: flags documented in the header, no `serve reset`, no `funnel`, no `--service` advertise, every serve mutation goes through `ts_cmd_serve`, rename happens before serve in `main` (static order check) |
+| `.github/workflows/ci.yml` | The bash 3.2 step additionally sources the script with stubbed `ts_cmd`/`ts_cmd_serve`/`read_reply` and drives `ask_everything` through all three answers and the 443-occupied menu |
+| `test/tailscale-status.test.ts`, `test/routes/system-routes-remote-access.test.ts` | Parser + route |
+| Docs | README install + remote-access sections, `docs/wiki/Installation.md`, `Remote-Access.md` (naming options table, Services caveat, path/port variants), `Mobile-Guide.md`, `Running-As-A-Service.md` (macOS login caveat), `FAQ.md`, `docs/security-architecture.md` §A, CLAUDE.md Scripts & Tunnel paragraph, `docs/tailscale-installer-plan.md` gets a pointer here. getcodeman.com copy lives outside the repo (maintainer handbook). |
+
+Changeset: `minor` (new flags, new subcommands, new API route).
+
+## 8. Test plan
+
+Automated (the gate): the static invariants above, the bash 3.2 container drive of the
+question phase, the JSON parser fixtures, the route test.
+
+Manual matrix, on a fresh Ubuntu 24 VM and on the Mac mini, since the previous plan's
+items never ran on a fresh machine:
+
+1. Tailscale absent, declined -> local-only, done screen shows the retrofit command.
+2. Tailscale absent, accepted -> install, login URL, operator, certs toggle polled, rename
+   question shown (default no), service, serve, URL verified, QR scans on a phone, PWA installs.
+3. Tailscale present and logged in on a pre-existing node -> rename default NO, URL is the
+   node name, `serve status` gains exactly one entry.
+4. `:443` root occupied -> path option -> `https://<node>/codeman` answers, hooks still
+   fire (raw port), `install.sh status` prints the path URL.
+5. Rename on a node that already has our serve mapping (`install.sh name`) -> off, rename,
+   re-add, `serve status` has no stale key.
+6. Re-run the one-liner -> quiet update, binding and name preserved, no prompts.
+7. `--yes` end to end; `CODEMAN_NONINTERACTIVE=1` end to end (no software installed).
+8. Uninstall -> mapping removed, other mappings intact, rename reversal offered.
+9. Mac mini: LaunchDaemon left alone with the message; done screen carries the login caveat.
+
+## 9. Phasing and open decisions
+
+**Phase 1 (this round):** the reorder, the three questions, one consent + one sudo, flags,
+the done screen with QR, Tailscale preflight-before-build, the path/port answer for an
+occupied 443, the rename step, `status` and `name` subcommands, docs.
+
+**Phase 2:** the in-app Tailscale row + QR, `codeman doctor` row, the `remote-access`
+route. Independent of phase 1 and useful on its own for existing installs.
+
+**Phase 3 (optional):** replace the bash service writers with `codeman service install`
+once that command can carry `CODEMAN_PASSWORD` behind an explicit flag; and a Tailscale
+Services flow if a tagged-fleet user asks for `codeman.<tailnet>.ts.net`.
+
+Decisions for the maintainer:
+
+1. **Rename default.** Decided 2026-09-20: always NO; the yes answer, `--name` and
+   `install.sh name` are the ways in. (The proposal was YES only when this run had joined
+   the tailnet, NO otherwise; rejected because the host is used for other things.)
+2. **Name pattern.** `codeman-<hostname>` (proposed; unique per machine, and two Codemans
+   on one tailnet stay distinguishable) versus plain `codeman` (nicer once, collides on the
+   second install, Tailscale silently appends `-1`).
+3. **Path versus port** as the default answer for an occupied 443. Proposed: path, because
+   the URL has no port and `--base-url` already exists for exactly this proxy shape.
+4. **Whether Phase 2 ships in the same release.** It is the part that helps people who
+   installed months ago.

docs/mobile-testing-report.md

@@ -156,8 +156,8 @@ There is no dedicated help button in the mobile UI. Help is accessible via:
 
 | Breakpoint | Class | Description |
 |------------|-------|-------------|
-| < 430px | `device-mobile` | Phone - most features hidden/simplified |
-| 430-768px | `device-tablet` | Tablet - intermediate layout |
+| < 600px | `device-mobile` | Phone - most features hidden/simplified |
+| 600-768px | `device-tablet` | Tablet - intermediate layout |
 | > 768px | `device-desktop` | Desktop - full features |
 
 Touch devices also get `touch-device` class regardless of screen size.

docs/omp-integration.md

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

docs/pi-integration-plan.md

@@ -0,0 +1,681 @@
+# Pi (pi.dev) Run Mode: Implementation Plan
+
+Tracking issue: [#206 "Plans to support pi.dev?"](https://github.com/Ark0N/Codeman/issues/206)
+
+Status: **IMPLEMENTED 2026-08-13** (see `docs/pi-integration.md` for the user-facing
+guide). Everything below is the design record; the open questions were resolved
+empirically against pi 0.84.1 and the answers are recorded inline as **RESULT**
+notes. Originally reworked 2026-08-06; **rechecked 2026-08-13 against master @
+`f39beb3` (v1.17.0)**, and every line anchor below was re-verified at that commit (the 1.11.2-era
+anchors drifted heavily: six releases landed in between, including the settings-surface overhaul and
+the codex predictive-echo work, both of which added new pi touchpoints, §2.10 and the Brain picker in
+Phase 3). Upstream facts verified against `@earendil-works/pi-coding-agent` **v0.84.1** (npm latest,
+published 2026-08-07) and the [`earendil-works/pi`](https://github.com/earendil-works/pi) repo (cite
+that name: upstream docs still contain stale `pi-mono` links from a repo rename). Line numbers are
+anchors for orientation, not contracts; they drift.
+
+---
+
+## 1. What Pi is
+
+[Pi](https://pi.dev) (MIT) is a minimal, extensible coding-agent harness. Facts below are verified
+against the upstream docs in `packages/coding-agent/docs/`.
+
+| Property         | Value                                                                                              |
+| ---------------- | -------------------------------------------------------------------------------------------------- |
+| Binary           | `pi` (`bin: { pi: 'dist/cli.js' }`)                                                                |
+| npm package      | `@earendil-works/pi-coding-agent`, latest **0.84.1** (2026-08-07; 0.84.0 was 2026-08-06); `legacy-node20` dist-tag at 0.74.2 |
+| Install          | `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`, or `curl -fsSL https://pi.dev/install.sh \| sh` (the curl installer also goes through global npm, so both uninstall via npm) |
+| Config dir       | `~/.pi/agent` (override: `PI_CODING_AGENT_DIR`). Holds `auth.json`, `trust.json`, `settings.json`, `models.json` (user-defined providers), `models-store.json` (cached catalogs), `keybindings.json`, `extensions/`, `skills/`, `prompts/`, `themes/`, `AGENTS.md`, `SYSTEM.md`, and the package trees `npm/` + `git/` |
+| Sessions         | `~/.pi/agent/sessions/--<cwd with / replaced by ->--/<timestamp>_<uuid>.jsonl`, tree-structured (`id`/`parentId`), format v3. Overrides: `PI_CODING_AGENT_SESSION_DIR`, `--session-dir` |
+| Credentials      | `~/.pi/agent/auth.json` (OAuth subscriptions + API keys, auto-refresh), plus ~34 provider env vars with **no common prefix**. 0.84.1 adds `pi auth check` (auth preflight with optional credential output) |
+| TUI              | Default: **main screen with terminal-owned scrollback**. Since **0.84.0** an experimental fullscreen mode exists, selectable via `--tui-mode fullscreen` **or at runtime through `/settings`**; the default remains the main-screen mode |
+| Providers        | 15+ (Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, xAI, OpenRouter, Copilot, Baseten since 0.84.0, ...). OAuth subscription login via `/login` for six: ChatGPT Plus/Pro, Claude Pro/Max, GitHub Copilot, xAI, OpenRouter, Radius |
+| Permission model | **No permission prompts at all.** No built-in sandbox, no MCP (none planned), no sub-agents, no plan mode, no to-dos, no background bash. Tools run with the user's own permissions |
+| Trust model      | "Project trust" gates **loading** of project-local `.pi/` config/extensions/skills and **installing missing project packages**, not tool execution. Triggered only when the cwd (or an ancestor) contains `.pi/settings.json`, `.pi/extensions\|skills\|prompts\|themes`, `.pi/SYSTEM.md`/`.pi/APPEND_SYSTEM.md`, or `.agents/skills`; a bare `.pi/` directory does NOT prompt. Global `defaultProjectTrust`: `ask` (default) / `always` / `never` |
+
+Three consequences shape the whole integration:
+
+1. **There is no `--dangerously-skip-permissions` analog and none is needed.** Pi never prompts for
+   tool approval. The Claude/Codex/Gemini/Antigravity pattern of "send the bypass flag so the session
+   is not stuck on a modal" does not apply. Codeman must not invent a flag here.
+2. **The one privileged knob is `--approve` / `-a`** (trust project-local files for this run), which
+   makes pi load and execute project `.pi/extensions` TypeScript **and run an npm install of missing
+   project packages**. That is the field the multi-user clamp has to cover. Its explicit inverse
+   `-na` / `--no-approve` exists, which lets the clamp force-deny rather than merely omit (§3, §5.2).
+3. **Provider keys cannot ride the env allowlist.** Pi's provider key vars (`ANTHROPIC_API_KEY`,
+   `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `HF_TOKEN`, `BASETEN_API_KEY`, ...) share no prefix, so
+   there is no way to admit them through `ALLOWED_ENV_PREFIXES` without widening the list for every
+   mode (§2.4).
+
+---
+
+## 2. Design decisions
+
+### 2.1 Mode identity
+
+`SessionMode` gains `'pi'`. Not a location overlay (unlike Docker/remote-SSH cases), not a web tab:
+a real sixth CLI backend with its own PTY, tmux session and respawn behaviour, exactly like
+`antigravity`. Append `pi` after `antigravity` in every enum/list to keep ordering consistent.
+
+| Surface          | Value                                                                 |
+| ---------------- | --------------------------------------------------------------------- |
+| `SessionMode`    | `'pi'`                                                                |
+| Display label    | `Pi`                                                                  |
+| Tab badge        | `pi` (two-letter lowercase, like `sh`/`oc`/`cx`/`gm`/`ag`)            |
+| Run button label | `Run PI` (short-label ternary in `_applyRunMode`, pattern `Run AG`)   |
+| Kill-menu label  | `Kill Tmux & Pi`                                                      |
+| Identity color   | **`#f472b6` (rose-400)**. Verified free: live computed values on the default skin are claude `#38b6f0`, opencode `#44b993`, codex `#2b8fd9`, gemini `#8ab4f8`, antigravity `#22d3ee`, shell `#98a2b1`, web `#38bdf8`; purple is codex's base hex and amber reads as the shell tab badge, so pink/rose (or orange `#fb923c`) are the only genuinely free hues. No `pi` CSS identifier collides anywhere (`mode-pi`, `.tab-mode.pi`, `.run-mode-dot.pi` all grep clean, re-checked at f39beb3) |
+| Env prefix       | `PI_`                                                                 |
+| Dependency id    | `pi`                                                                  |
+| Status endpoint  | `GET /api/pi/status`                                                  |
+
+### 2.2 `isExternalCliMode()` yes, `isAltScreenStripMode()` no
+
+Pi joins `isExternalCliMode()` (`session.ts:164-167`): its own TUI, its own output format, so the
+Ralph tracker, `BashToolParser`, token/CLI-info scraping and the `❯` readiness probe all stay off
+(gates at `session.ts:1100`, `:1701`, `:2000`, `:2103`), and readiness falls back to the output
+stabilization used by the other external CLIs.
+
+Pi stays **out** of `isAltScreenStripMode()` (`session.ts:197-199`, currently codex/claude/gemini;
+antigravity and opencode are deliberately excluded). Pi's default TUI renders into the main screen
+with terminal-owned scrollback, so there is nothing to strip. The fullscreen mode **shipped in
+0.84.0 and is runtime-switchable via `/settings`**, so Codeman cannot assume a pi session stays
+main-screen for its lifetime; staying out of the strip list is exactly what makes that safe (the alt
+screen is load-bearing when the user flips to fullscreen, as it is for `opencode`). Putting pi IN
+the strip list would corrupt fullscreen sessions. Three mirrors must stay consistent (all unchanged
+for pi, i.e. pi appears in none of them): the replay-side strip in `session-routes.ts:2275`, the
+live-stream twin in `session.ts`, and the frontend `_sessionUsesServerMouseStrip()` in
+`terminal-ui.js` (usages `:3432`, `:3697`).
+
+### 2.3 tmux required, no direct-PTY fallback, no per-mode configurator
+
+Same rule as the other external CLIs: `pi` mode throws if tmux is unavailable. Add a fourth block to
+the guard chain at `session.ts:1751-1768` (antigravity's is `:1765-1768`).
+
+**No `_configurePi()` is needed.** Opencode/codex/gemini each have a tmux-`setenv` configurator
+(`tmux-manager.ts:1709-1727`), but antigravity has none: it relies entirely on the generic
+`applyEnvOverrides()` (`tmux-manager.ts:1643`, `VALID_KEY = /^[A-Z_][A-Z0-9_]*$/`), which runs for
+every mode in both create (`:1880`) and respawn (`:2107`) and injects via socket-scoped
+`tmux setenv`, never the spawn command line. Pi follows the antigravity precedent: `PI_*` overrides
+flow through `applyEnvOverrides()` and nothing else.
+
+Pi joins the truecolor branches: `buildEnvExports()` (`tmux-manager.ts:1604-1609`,
+`export COLORTERM=truecolor` + `unset NO_COLOR` for codex/gemini/antigravity) and the attach-env
+condition at `session.ts:1400-1402` (`buildMuxAttachEnv(...)`, whose comment says it must mirror
+`buildEnvExports`). Add `|| mode === 'pi'` to both, or the tmux session and the attach client
+disagree about color depth.
+
+### 2.4 Env prefix: `PI_` only
+
+Add `'PI_'` to `ALLOWED_ENV_PREFIXES` (`schemas.ts:125`) and to the prose error message at `:163`
+(two edits: the message hardcodes the list, and since 1.12+ it also names the exact-key allowlist,
+currently `...ANTIGRAVITY_* keys and CLAUDE_CONFIG_DIR are allowed.`; there is now a separate
+`ALLOWED_ENV_KEYS` exact-key set alongside the prefix list, which pi does not need to touch). That
+covers every documented variable pi reads: `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`,
+`PI_PACKAGE_DIR`, `PI_OFFLINE`, `PI_SKIP_VERSION_CHECK`, `PI_TELEMETRY`, `PI_CACHE_RETENTION`,
+`PI_SHARE_VIEWER_URL`, `PI_HARDWARE_CURSOR`, `PI_EXPERIMENTAL` (whose meaning 0.84.0 extended to
+strict JSON-schema tool sampling). (Pi also *sets* `PI_CODING_AGENT=true` and `AI_AGENT=pi` in child
+processes; those are output markers, not inputs, and need nothing from us.)
+
+**Deliberately not added:** `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`,
+`GROQ_API_KEY`, `MISTRAL_API_KEY` and the other ~28 provider keys. `ALLOWED_ENV_PREFIXES` is a
+single global list applied by one Zod refine with no mode context (`safeEnvOverridesSchema`,
+`schemas.ts:153-165`), so allowlisting bare provider keys for pi would widen the allowlist for
+**every** mode at once, violating the multi-CLI prefix discipline in CLAUDE.md. Users authenticate
+pi through `/login` (stored in `~/.pi/agent/auth.json`, auto-refreshed) or by exporting the key in
+the Codeman server process's own environment.
+
+Making the allowlist mode-aware is the clean fix, listed as a follow-up in §9. Do not smuggle it
+into this change.
+
+### 2.5 Docker credential policy: seed files, not the whole dir
+
+`CRED_STORES` (`docker-hosts.ts:597-605`; file unchanged since the 2026-08-06 verification) gets a
+`.pi/agent` entry. Nested `rel` paths already work (`.config/gcloud` maps to seed name
+`.config-gcloud` via the `replace(/\//g, '-')` at `:620`). Unlike antigravity, which needed **no**
+entry (`agy` nests all state under `~/.gemini/antigravity-cli/`, already covered by the `.gemini`
+policy, per the comment at `:599-602`), pi has its own top-level dir and needs its own entry. Use
+`seedFiles`, **not** `seedWhole`:
+
+```ts
+{ rel: '.pi/agent', seedFiles: ['auth.json', 'settings.json', 'trust.json', 'models.json', 'models-store.json'] },
+```
+
+Rationale: `~/.pi/agent` also contains `sessions/`, `extensions/`, `skills/` and the installed
+package trees (`npm/`, `git/`), which on an active host is easily gigabytes; `seedWhole` would
+`cp -a` all of it into every container start. The five seeded files are what pi needs to
+authenticate and behave consistently: `models.json` is in the list because it holds user-defined
+custom providers, and omitting it would silently strip those inside containers. Seeding (RO mount
+then copy) also means the in-container pi never writes refreshed OAuth tokens back to the host,
+which is the whole point of the seeding policy, and bind mounts stay excluded from `docker commit`
+so exports remain secret-free.
+
+Trade-off to accept and document: in-container pi sessions are not visible host-side, so `pi -c`
+inside a Docker case only sees that container's own history. Codex shares `sessions/` RW precisely
+because Codeman reads it host-side for the response viewer; there is no such reader for pi yet
+(the response-viewer follow-up in §9 would justify flipping this).
+
+### 2.6 The `pi` binary name is generic
+
+Unlike `agy`/`codex`/`gemini`, `pi` is a short, common name (Raspberry Pi tooling, personal scripts,
+`$PATH` accidents). The resolver must not blindly trust a hit. None of the existing external-CLI
+resolvers execute their binary (only `claude-cli-resolver.ts` does, via the cached
+`getClaudeCliVersion()`, skipped under vitest), so the sanity check is new ground: model it on
+`getClaudeCliVersion()`. Run `pi --version` once via `execFileSync`, cache the result module-level,
+skip under `VITEST`, and require output matching `/^\d+\.\d+\.\d+/`; on mismatch treat the binary as
+unavailable and log the rejected path. Surface `{ available, path, version }` from
+`GET /api/pi/status` so a misresolution is diagnosable from the UI (additive relative to the sibling
+endpoints' `{ available, path }`). The `dependency-registry` entry carries `versionArg: '--version'`
+for `codeman doctor`.
+
+### 2.7 tmux extended keys (a real pi-specific footgun)
+
+Pi documents (`docs/tmux.md`, verified verbatim) that without
+
+```tmux
+set -g extended-keys on
+set -g extended-keys-format csi-u
+```
+
+tmux collapses `Shift+Enter` and `Ctrl+Enter` into a plain `\r` (and `Alt+Enter` into `\x1b\r`), and
+pi's editor uses those for newline vs submit. `extended-keys-format` requires tmux 3.5+; tmux
+3.2-3.4 works with `extended-keys on` alone (pi then falls back to xterm `modifyOtherKeys`).
+Codeman's own browser input path sends `\r` for submit, so basic use works unconfigured, but
+newline-in-editor is degraded both for a user typing in an attached terminal (`sc`) and potentially
+for the browser Shift+Enter path.
+
+Upstream recommends `~/.tmux.conf` and notes the setting may need a full `tmux kill-server` restart
+to take effect. **Codeman must NEVER run `kill-server` on its socket** (it would kill every live
+session, including `w1`/`w2`/`w3`). Action: attempt to set both options **server-scoped on
+Codeman's own socket only** (`tmux -L codeman set -s ...`, never `-g` on the user's default socket)
+at the point the tmux server is first started, verify with `tmux -L codeman show-options -s` and an
+empirical Shift+Enter test which scope actually takes for the installed tmux version, and fall back
+to a documented manual step in `docs/pi-integration.md` (a `~/.tmux.conf` snippet plus the
+kill-server caveat) if it cannot be applied safely to an already-running server. Upstream does not
+discuss socket- or server-scoped configuration at all, so this verification is original work, not a
+doc lookup.
+
+**RESULT (measured, tmux 3.4 + pi 0.84.1):** `tmux -L <socket> set -s extended-keys on` takes effect
+on an **already-running** server with **no `kill-server`** — pi's own startup warning
+(`Warning: tmux extended-keys is off…`, a convenient in-band probe) disappears for the next session
+started afterwards. `extended-keys-format` does **not exist on tmux 3.4** and errors with
+`invalid option: extended-keys-format`, so the two options must be issued independently rather than
+chained. Decision: Codeman does **not** set this itself — it is a server-wide tmux option affecting
+every session of every backend, so silently changing key encoding is not Codeman's call. It is
+documented as a user step in `docs/pi-integration.md` instead, carrying the measured facts.
+
+### 2.8 The completeness trap: which mode tables fail loud vs silent
+
+Adding `'pi'` to the `SessionMode` union makes some omissions compile errors and leaves others
+silent. The plan calls this out so review can focus on the silent ones.
+
+**Loud (typecheck fails until edited):** `getModeLabel()` (`session.ts:168-183`, exhaustive switch
+with no default), `defaultDockerCommandForMode` and `defaultRemoteCommandForMode` (both typed
+`Record<...CommandMode, string>`), **but only after** `RemoteCommandMode` (`types/session.ts:48-51`)
+and `DockerCommandMode` (`:157-161`) are widened: both are `Extract<SessionMode, '...'>` with every
+member spelled out, so forgetting the `Extract` lists keeps `tsc` green while docker/remote pi cases
+silently fall back to `exec bash -l` via the `|| commands.shell` on the lookup. Edit union + both
+`Extract` lists + both `Record` literals together.
+
+**Silent (compiles clean, mode just doesn't work):**
+
+- `appendResumeFlag()` (`tmux-manager.ts:1030-1042`) has a `default:` arm; a missing `case 'pi'`
+  silently drops docker resume.
+- `buildSpawnCommand()` (`:770-825`) and `buildPathExport()` (`:1680-1707`) are if-chains with
+  fallthrough returns; a missing branch spawns pi as a login shell / with no PATH augmentation.
+- `isExternalCliMode()` / `isAltScreenStripMode()` are boolean chains.
+- The `runMode` accessor's **setter whitelist** (`session-ui.js:2949-2960`) coerces any unknown mode
+  to `'claude'`. Omitting `pi` there makes the mode **unselectable while every other edit appears to
+  work**: this is the single most deceptive omission in the frontend.
+- `window.__codemanCliAvailable` (injected by `renderIndexHtml`, `server.ts:1375-1407`): the client
+  treats a **missing key as available** (`isCliAvailable` in settings-ui.js), so forgetting the
+  injection un-gates pi on boxes without the CLI instead of hiding it.
+
+### 2.9 The Daylight skin cascade eats per-mode run-button colors
+
+A finding that changes the CSS work (verified empirically with computed styles on the live
+instance, re-confirmed at f39beb3): `styles.css:13681` opens a nested skin block,
+`html:not([data-skin="og"]) { ... }`, and the **default skin is `daylight-blue`, not `og`**, so the
+block is live for every default-skin user. Inside it, `.btn-toolbar.btn-run` is re-declared
+generically and per-mode only for claude/opencode/codex (codex at `:13787`). CSS nesting adds the
+wrapper's specificity (the nested rules resolve to (0,3,1) vs (0,3,0) for
+`.btn-toolbar.btn-run.mode-X`), so **gemini's and antigravity's toolbar gradients are dead on the
+default skin**: both render the generic claude gradient today, still unfixed as of f39beb3. The
+base-sheet rules (gemini/antigravity at `:4406`/`:4420`) only ever render on the `og` skin. Since
+1.12+ styles.css itself documents this trap in comments (`:9214`, `:11091`), which confirms the
+mechanism.
+
+Consequences for pi:
+
+- The toolbar gradient needs **two** rules: one in the base sheet (`:4420` area, for `og`), and one
+  **inside** the `13681` block next to codex's (`:13787` area), using the block's own idiom
+  (or the color is invisible to the average user).
+- `mobile.css` phone-toolbar colors need `!important` on `background`/`border-color`/`color`,
+  exactly as the CLAUDE.md gotcha prescribes. Antigravity's phone block (`mobile.css:895-910`,
+  inside the `@media (max-width: 430px)` opened at `:338`) has no `!important` and is dead on the
+  default skin; do not copy that mistake.
+- Three surfaces work from base rules alone (verified): run-mode **dots** (list at `:4506-4516`;
+  the skin block overrides only claude/opencode/codex/shell dots, so a base-sheet
+  `.run-mode-dot.pi` renders as authored), **tab badges**, and the **welcome button** (the skin
+  block overrides only claude/opencode/tunnel welcome buttons).
+- Optional, separate cleanup (not this change): gemini/antigravity could get the same in-block
+  treatment to resurrect their colors.
+
+### 2.10 Local-echo policy: pi lands on the buffer overlay by default
+
+New since the first draft of this plan: the codex predictive-echo work (1.13+) introduced a
+per-session echo policy in `_updateLocalEchoState()` (terminal-ui.js, `_localEchoPolicy` set at
+`:2837`): `codex → 'predict'` (write-through predictive echo), `shell → 'off'`, **everything else
+→ 'buffer'** (the `LocalEchoOverlay` that buffers typed text until Enter). Pi therefore gets the
+buffer overlay on touch devices with zero edits, via the fallthrough.
+
+That default is a real open question, not a freebie: the codex history (issues #218/#219/#220/#222)
+shows that a composer which re-renders per keystroke (live-filtering slash picker, server-side
+cursor movement, wrap-as-you-type) is starved by buffer-until-Enter, and pi's editor is exactly
+such a composer. Decision for v1: ship with the default `'buffer'` policy but make phone-profile
+typing an explicit E2E gate (§7 step 4); if pi's editor mis-renders under the overlay, the cheap
+fallback is forcing `'off'` for pi (one branch in `_updateLocalEchoState`), and teaching the
+predict path pi's composer row is a follow-up, not a v1 requirement.
+`test/local-echo-codex-gating.test.ts` pins the per-mode policy via
+`it.each(['claude', 'gemini', 'opencode'])` lists (`:193`, `:376`); add `'pi'` to those lists once
+the buffer decision is confirmed (or pin the `'off'` branch if that is the outcome).
+
+**RESULT (measured, pi 0.84.1, iPhone 14 Pro profile + a PTY-level A/B):** the buffer policy
+**holds**; codex's failure mode does **not** reproduce. Pi's slash picker re-filters on the **whole
+composer content**, not on per-keystroke deltas: a one-shot literal write of `/set` (what the overlay
+flush does) filters the picker to `settings` **identically** to sending `/ s e t` as five separate
+keystrokes, and the delayed `\r` then selects it and opens the settings menu. Prose prompts buffer
+correctly (`pendingText` right, nothing on the PTY before Enter), flush on Enter, and are accepted as
+a single prompt. `'pi'` was added to both `it.each` lists. The `'off'` fallback stays documented but
+unused.
+
+---
+
+## 3. Config surface: `PiConfig` to CLI flags
+
+```ts
+/** Pi CLI session configuration */
+export interface PiConfig {
+  /** Model pattern or ID. Supports `provider/id` and a `:<thinking>` suffix (e.g. `sonnet:high`). Passed via --model. */
+  model?: string;
+  /** Provider name (anthropic, openai, google, ...). Passed via --provider. */
+  provider?: string;
+  /** Reasoning level. Passed via --thinking. */
+  thinking?: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+  /** Continue the most recent session (-c). Per-cwd scoping is strongly implied upstream but not documented; treat as probable. */
+  continueSession?: boolean;
+  /** Resume a specific session by ID or partial UUID (--session). Codeman deliberately accepts ids only, never paths. */
+  resumeSessionId?: string;
+  /**
+   * Tri-state project trust (repo-local `.pi/` settings/extensions/skills, plus installing
+   * missing project packages):
+   *   true  -> --approve   (trust for this run; loads and EXECUTES repository TypeScript)
+   *   false -> --no-approve (force-deny; the trust prompt never appears)
+   *   absent -> pi's own defaultProjectTrust (ask).
+   * Multi-user: MATERIALIZED to false for non-granted owners (§5.2).
+   */
+  approveProjectTrust?: boolean;
+}
+```
+
+Flag mapping in `buildPiCommand()` (new, `tmux-manager.ts`, directly after `buildAntigravityCommand`
+at `:718-736`; every builder there regex-allowlists each user value and silently drops failures
+because the result lands in a `bash -c "..."` string):
+
+| Field                 | Flag                            | Validation                                                                        |
+| --------------------- | ------------------------------- | --------------------------------------------------------------------------------- |
+| `approveProjectTrust` | `--approve` / `--no-approve` / nothing | tri-state boolean, clamped (§5.2)                                          |
+| `model`               | `--model <v>`                   | `/^[a-zA-Z0-9._\-/:]+$/` (`:` for `sonnet:high`, `/` for `openai/gpt-4o`)         |
+| `provider`            | `--provider <v>`                | `/^[a-z0-9-]+$/`                                                                  |
+| `thinking`            | `--thinking <v>`                | runtime allowlist of the 7 enum values (defense in depth beyond Zod)              |
+| `resumeSessionId`     | `--session <v>`                 | `/^[a-zA-Z0-9._-]+$/` (same shape as `RESUME_ID_SAFE`, `:1021`; excludes paths on purpose) |
+| `continueSession`     | `-c`                            | boolean; **skipped when a valid `resumeSessionId` is present** (the two conflict) |
+
+**Not** wired in v1, with reasons:
+
+- `--api-key <key>`: ⚠️ **never wire this.** It puts a provider secret on the spawn command line,
+  which is exactly what the socket-scoped `tmux setenv` discipline exists to prevent (visible in
+  `ps`, tmux server state, and logs). Listed here so nobody "helpfully" adds it later.
+- `--tui-mode` (released in 0.84.0): never passed by Codeman. The main-screen default is the
+  friendly case for the browser terminal, and fullscreen remains the user's own runtime choice via
+  `/settings` (§2.2 is designed for that). `--use-theme` (still unreleased) likewise.
+- `--name <name>` (`-n`): nice for `/resume` readability, but names contain spaces and would be the
+  first user-controlled value needing real shell quoting in `buildSpawnCommand`. Defer.
+- `--no-session`: ephemeral mode fights respawn/resume. Defer.
+- `-p`/`--print`, `--mode json`, `--mode rpc`: non-interactive transports, a different product shape
+  (§9). Note upstream already shipped a breaking change to JSON-mode `message_update` framing, so
+  any future consumer must assemble deltas.
+- `--tools` / `--exclude-tools` / `--no-tools` / `--no-builtin-tools` (`-t`/`-xt`/`-nt`/`-nbt`): a
+  genuinely useful "read-only session" affordance (0.84.0 also added a `defaultTools` setting), but
+  it needs UI design. Follow-up.
+- `-r`/`--resume` (interactive picker), `--fork`, `-e`/`--extension`, `--skill`, `--system-prompt`,
+  `--append-system-prompt`, `--export`, `--models`, `--list-models`: not session-manager concerns in
+  v1. (`-e` matters later: §9's extension follow-up notes CLI extensions load before trust
+  resolution.)
+
+---
+
+## 4. Implementation phases
+
+### Phase 1: Backend core
+
+| File                                | Change                                                                                                       |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `src/utils/pi-cli-resolver.ts`      | **New**, mirror `antigravity-cli-resolver.ts` (65 lines: search-dir list, module-level cache with `''` negative sentinel, `which pi` first). Search dirs: `~/.local/bin`, `/usr/local/bin`, `~/.bun/bin`, `~/.npm-global/bin`, `~/bin`. Add the `pi --version` sanity probe from §2.6 (execFileSync, cached, vitest-skipped). Export `resolvePiDir()`, `isPiAvailable()`, `getPiCliVersion()` |
+| `src/utils/index.ts`                | Re-export the three (resolver block `:30-36`)                                                                |
+| `src/types/session.ts`              | `SessionMode` union `:46`; **both `Extract` lists**: `RemoteCommandMode` `:48-51`, `DockerCommandMode` `:157-161` (§2.8); new `PiConfig` after `AntigravityConfig` (`:325-333`); `SessionState.piConfig` after `:486`; `@fileoverview` mode list `:11` + config list `:17` |
+| `src/mux-interface.ts`              | `piConfig?: PiConfig` on `CreateSessionOptions` (config block ends `:78`) and `RespawnPaneOptions` (ends `:109`) |
+| `src/session.ts`                    | `isExternalCliMode()` `:164-167` (+pi); `getModeLabel()` `:168-183` (+`'Pi'`); `_piConfig` field decl `:466-470`; ctor option `:556-563` + apply `:652-654`; `toState()` `:1227-1230`; `_buildRespawnPaneOptions()` `:1466-1469` (single source of truth shared by `startInteractive` and `reattachRemote`); `startInteractive()` createSessionOptions `:1680-1683`; COLORTERM attach-env condition `:1400-1402` (+pi); requires-tmux guard chain `:1751-1768` (new block: "Pi sessions require tmux for env override injection via setenv") |
+| `src/tmux-manager.ts`               | `buildPiCommand()` after `:736` per §3; `buildSpawnCommand()` signature `:770-779` + dispatch branch after `:822-825`; `appendResumeFlag()` `:1030-1042` (`case 'pi': return \`${modeCommand} --session ${resumeId}\`;`); `buildEnvExports()` truecolor branches `:1604-1609` (+pi); `buildPathExport()` `:1680-1707` (+pi branch calling `resolvePiDir()`); missing-CLI error chain in `createSession` `:1788-1806` (+pi, install hint `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`; note `respawnPane` deliberately has no such check); `piConfig` threading at the four sites `:1748`, `:1817`, `:2041`, `:2080`. **No `_configurePi`** (§2.3) |
+| `src/config/dependency-registry.ts` | New entry after antigravity's (`:101-108`; file unchanged since 2026-08-06): `{ id: 'pi', label: 'Pi CLI', category: 'core', required: false, usedBy: ['Pi sessions'], resolvers: [{ match: ALL, resolver: { kind: 'path', bins: ['pi'], versionArg: '--version' } }] }` |
+| `src/docker-hosts.ts`               | `defaultDockerCommandForMode` `:138-149`: `pi: 'exec pi'`. `CRED_STORES` `:597-605`: the `.pi/agent` seedFiles entry per §2.5 (nested `rel` already handled at `:613-645`). File unchanged since 2026-08-06 |
+| `src/remote-hosts.ts`               | `defaultRemoteCommandForMode` `:92-118`: `pi: remoteLoginShellCommand('pi')` (`remoteLoginShellCommand` at `:88-90`). Login-shell routing is mandatory (the #209/e803186 lesson: ssh remote-command exec sees only sshd's minimal PATH, and npm's global bin is usually only on PATH via rc files) |
+
+### Phase 2: Web layer
+
+| File                               | Change                                                                                          |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `src/web/schemas.ts`               | `'PI_'` in `ALLOWED_ENV_PREFIXES` `:125` **and** the prose error message `:163` (which now also names `CLAUDE_CONFIG_DIR`; the `ALLOWED_ENV_KEYS` exact-key set needs no change); new `PiConfigSchema` after `AntigravityConfigSchema` (`:256-271`), mirroring §3's regexes, `.optional()`, not `.strict()`; `piConfig` on `CreateSessionSchema` (`:299` area) and `QuickStartSchema` (`:712` area); `'pi'` in all three mode enums (`:285`, `:708`, cron `agentType` `:1214`; they are byte-identical and there is no fourth); `pi` key in `RemoteCommandOverridesSchema` `:426-436` (it is `.strict()`, so an unknown key is a hard error today; one edit covers both remote `:501` and docker `:577` reuse) |
+| `src/web/routes/session-routes.ts` | Thread `piConfig` through create (`POST /api/sessions`): disk-strip exclusion chain `:705-712`, availability gate `:782-790` (+`isPiAvailable` with install-hint error), model resolution `:825-838` (`mode === 'pi' ? body.piConfig?.model : ...`), clamp call `:845`, Session ctor `:860` (`piConfig: mode === 'pi' ? gatedPiConfig : undefined`). Quick-start (`POST /api/quick-start`, handler `:2559`): remote-case config rejection `:2614-2621` and docker-case `:2645-2652` (+`piConfig`: per-CLI config does not cross ssh or the bind mount), hooks-scaffold exclusions `:2801`/`:2809`, availability gate `:2744-2752` (local-case branch only), env-strip chains `:2833`/`:2863`, model resolution `:2885`, clamp `:2897`, ctor `:2913`. **Extend `clampExternalCliBypassForOwner()`** (`:305-336`, doc comment above): fifth param + return field; pi joins the **materialize** branch per §5.2. Alt-screen replay-strip at `:2275` unchanged (pi not in it, §2.2) |
+| `src/web/routes/system-routes.ts`  | `GET /api/pi/status` after the antigravity handler (`:418-426`; file unchanged since 2026-08-06), same shape plus `version` (§2.6); update the "CLI Integrations" prose comment `:377` |
+| `src/web/server.ts`                | Restore path: `piConfig: muxSession.mode === 'pi' ? savedState?.piConfig : undefined` after `:2636`. **`renderIndexHtml` CLI-availability injection `:1375-1407`**: add `isPiAvailable` to the dynamic-import tuple (`:1382`) and a `pi` key to the injected object (`:1399`). Per §2.8 a missing key reads as *available*, so this is a correctness edit, not polish |
+
+### Phase 3: Frontend
+
+The antigravity touchpoints are the template. Since the first draft, the settings-surface overhaul
+moved most anchors and added one **new touchpoint** (the clone-repo Brain picker below).
+`constants.js`, `api-client.js`, `ralph-wizard.js`, `cron-ui.js`, `webview-tabs.js` and `sw.js`
+still need **no** changes (re-verified zero mode coupling at f39beb3; cron-ui reads the `<select>`
+generically and special-cases only `shell`).
+
+| File                | Change                                                                                                 |
+| ------------------- | ------------------------------------------------------------------------------------------------------ |
+| `index.html`        | Welcome button `welcomePiBtn` after Gemini's (antigravity's is `:347`; there is deliberately no codex welcome button), `display:none` default, `onclick="app.setRunMode('pi'); app.runPi()"`, text `Run Pi`; run-mode-option row with `.run-mode-dot.pi` after antigravity's (`:526-528`), before the `.run-mode-sep` `:529`; cron `<option value="pi">Pi</option>` after `:803`; **NEW: the clone-repo "Brain" picker** (`cloneCaseBrain`, `:2476-2486`): add `<option value="pi" data-cli="pi">Pi</option>` after the antigravity option `:2483` (gating is automatic: session-ui.js `:2107-2115` hides options whose `data-cli` fails `isCliAvailable`, and `:2250` reads the value at clone time); docker image hint `:2624` (`claude/codex/gemini/opencode/agy` + pi). No per-CLI remote-command override field needed (only codex has one, `:2559`) |
+| `session-ui.js`     | `@fileoverview` mode list `:2`; `run()` dispatch branch after `:400-402`; `_refreshRunModeAvailability` list `:468` (+`'pi'` as a quoted literal, the static test in §6 demands it); short-label ternary `:565` (+`'Run PI'`); **the `runMode` setter whitelist `:2949-2960`** (§2.8, the deceptive one); new `runPi()` modeled on `runAntigravity()` `:1170-1219`: same remote/docker skip, same `_beginSessionLaunchStatus` frame, probes `/api/pi/status` reading `(await res.json()).data.available` (envelope!), **sends no `piConfig` at all** (no bypass exists and trust defaults are pi's own; envOverrides still sent for local cases), install-hint error text matching Phase 1's; `isAltMode` `:1233` and `isExternalCli` `:1263` four-way comparisons (+pi) |
+| `settings-ui.js`    | `applyWelcomeCliVisibility()` `:1176-1191`: add `['welcomePiBtn', 'pi']`                               |
+| `app.js`            | Response-viewer agent label `:1998-2009` (+pi -> `'Pi'`); tab badge ternary `:3884` (`<span class="tab-mode pi" aria-hidden="true">pi</span>`; claude stays badge-less); kill-title ternary `:5046-5057` (`Kill Tmux & Pi`)                                                    |
+| `panels-ui.js`      | Command-palette `labels` map `:430` (+`pi: 'Pi'`; the `\|\| mode` fallback means this is cosmetic, not load-bearing) |
+| `mobile-overview.js`| `MOBILE_OVERVIEW_RUN_MODES` `:55-62`: `{ mode: 'pi', label: 'Pi', short: 'Pi' }` after antigravity `:60`, before the shell entry. Nothing else: the Run-button badge (`:499`) and menu builder (`:554-556`) consume the list generically, and the buttons carry `btn-toolbar btn-run mode-pi`, which is exactly why they inherit the §2.9 cascade problem and its fix |
+| `terminal-ui.js`    | Badge-row comment `:1750` only (the badge itself is a raw `s.mode` passthrough, no list to extend). `_sessionUsesServerMouseStrip` unchanged (§2.2). `_updateLocalEchoState` unchanged for v1 (§2.10: pi lands on `'buffer'` via the fallthrough; only touch it if E2E forces the `'off'` fallback) |
+| `i18n.js`           | `'Run Pi': '运行 Pi'` in the zh-CN table (`:102-107`, matches the welcome-button text; short labels like `Run PI` are deliberately untranslated, as are the other modes')                                              |
+| `styles.css`        | Tab badge `.session-tab .tab-mode.pi` after `:2157` (`background: rgba(244,114,182,0.2); color: #f472b6;`); add `.session-tab .tab-mode.pi` to the light-skin ink list `:325-336` (gemini + antigravity are its precedent, `:332`); welcome `.welcome-btn-pi` + `:hover` after antigravity's `:3366` block, rose family (e.g. base `linear-gradient(135deg, #33121f 0%, #9d174d 55%, #be185d 100%)`, border `rgba(244,114,182,0.4)`, text `#fce7f3`); toolbar gradient pair `.btn-toolbar.btn-run.mode-pi, .btn-toolbar.btn-run-gear.mode-pi` + `:hover` after `:4420`'s antigravity block; `.run-mode-dot.pi { background: #f472b6; }` in the dot list `:4506-4516`; **and the §2.9 rule inside the Daylight block** next to codex's `:13787` (e.g. `background: linear-gradient(135deg, #be185d, #f472b6); border-color: #be185d; color: #fff1f7;`). The dot needs no skin-block entry (the block overrides only claude/opencode/codex/shell dots; gemini/antigravity dots already fall through correctly) |
+| `mobile.css`        | Phone toolbar block after `:910` inside the `@media (max-width: 430px)` opened at `:338`: `mode-pi` base + `:active`, **with `!important` on background/border-color/color** (§2.9; antigravity's block `:895-910` omits it and is dead); light-skin override entry after `:2985` with the same four-skin `html:is(...)` prefix as its siblings |
+
+### Phase 4: Docker image and installer
+
+Both files are unchanged since the 2026-08-06 verification; all anchors stand.
+
+- `docker/agent.Dockerfile`: a **separate** `RUN` step after the antigravity block (`:38-45`), not a
+  fifth line in the shared npm block (`:31-36`), because pi documents `--ignore-scripts` and that
+  flag must not silently change how the other four install:
+
+  ```dockerfile
+  # Pi (pi.dev). Upstream documents --ignore-scripts (pi needs no lifecycle scripts);
+  # kept out of the shared npm block above so the flag cannot affect the other CLIs.
+  RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent \
+   && npm cache clean --force \
+   && pi --version
+  ```
+
+  Implementation checklist item: the gid-0 pre-created dirs at `:64-68` include `.claude/projects`
+  and `.codex/sessions`; verify whether the cred-seed copy into `~/.pi/agent` creates its target
+  dir in a fresh container or whether `.pi/agent` must join that `mkdir` line. Rebuild with
+  `node scripts/build-agent-image.mjs --no-cache` (the script itself needs no change; nothing in it
+  is CLI-specific). The cached npm layer has silently frozen a CLI at a broken version before; see
+  `docs/docker-cases.md`.
+- `install.sh` (six edit sites, all verified): `PI_SEARCH_PATHS` block after `:125` (mirror the
+  resolver's dirs); `check_pi` / `get_pi_path` pair inserted at `:531` (antigravity's pair spans
+  `:504-530`); the satisfying-AI-CLI chain `:2032-2063` (`has_pi` local at `:2037` area, detect
+  block after `:2059`, widen the five-way test at `:2061` and the warn text at `:2063`); the menu
+  option-4 text `:2070`; the skip-path hints `:2115-2116` (add
+  `npm install -g --ignore-scripts @earendil-works/pi-coding-agent   (Pi)`); the final no-CLI
+  reminder `:2416-2423` (add `check_pi` to the condition and a pi line to the echo block).
+  Detection plus a hint only; do **not** add an auto-install path in this change.
+
+### Phase 5: Docs
+
+- `docs/pi-integration.md` (**new**, user-facing): install (both installers uninstall via npm), auth
+  (`/login` OAuth for six providers vs API keys; `pi auth check` for preflight; Claude Pro/Max
+  third-party harness usage bills as Anthropic "extra usage" per token, not plan limits; OpenRouter
+  login supports pasting the redirect URL, which matters over remote SSH), what Codeman wires up
+  and deliberately does not (§3, incl. never passing `--tui-mode`), the tmux extended-keys note
+  from §2.7 with the manual `~/.tmux.conf` fallback, Docker/remote behaviour (in-container sessions
+  invisible host-side), the trust model in §1 words, known gaps.
+- `CLAUDE.md`: tech-stack line (six CLIs + `SessionMode` union), the env-prefix gotcha bullet, the
+  multi-CLI prefix-discipline bullet, the "External CLI modes" key-pattern paragraph (note it now
+  also carries the codex predictive-echo block; pi's echo-policy decision from §2.10 belongs in the
+  same paragraph), the `src/utils/` resolver list.
+- `docs/architecture-invariants.md`: the external-CLI-modes section. ⚠️ Its anchor was already
+  renamed once to `#external-cli-modes-opencode-codex-gemini-antigravity` while CLAUDE.md's link
+  text still shows the old name; when renaming again for pi, update every inbound link (CLAUDE.md
+  and this file).
+- `docs/docker-cases.md` (cred-seeding table + supported modes + image contents),
+  `docs/remote-sessions.md` (`RemoteCommandMode`), `docs/cron-guide.md` + `docs/cron-discovery.md`
+  (`agentType` enum; note the readiness caveat from §6's cron paragraph),
+  `docs/security-architecture.md` (env prefix allowlist row).
+- `README.md` + `README.zh-CN.md`: six CLIs.
+- `package.json` keywords: `pi`.
+- Update the issue #206 thread when it ships.
+
+---
+
+## 5. Security checklist
+
+1. **Command injection.** Every `PiConfig` value is regex-validated in `buildPiCommand()` before
+   entering the `bash -c "..."` string; anything failing validation is dropped, not escaped
+   (matching the four existing builders). No user string reaches the spawn line unvalidated. Pinned
+   by a "rejects unsafe values" test per field.
+2. **Multi-user clamp, materialize branch.** `approveProjectTrust` is the privilege-shaped field: it
+   makes pi execute repository-supplied TypeScript and install project packages.
+   `clampExternalCliBypassForOwner()` (`session-routes.ts:305-336`) has two branches, and pi belongs
+   in the **gemini-style materialize branch**, not the codex/antigravity only-if-sent branch:
+   pi's absent-config default is an *interactive trust prompt the session user can answer
+   themselves in the terminal*, so merely omitting `--approve` is not a clamp. For a non-granted
+   owner, materialize `{ ...(piConfig ?? {}), approveProjectTrust: false }` so `buildPiCommand`
+   always emits `--no-approve` and the prompt never appears. Both call sites (`:845`, `:2897`)
+   widen. This helper still has **zero test coverage** (re-confirmed at f39beb3); §6 adds the first
+   tests.
+3. **Secrets stay off the command line.** `PI_*` overrides flow through `applyEnvOverrides()` /
+   socket-scoped `tmux setenv`, never inlined into the spawn string. No `-e` at container create
+   time. And `--api-key` is never wired (§3): it would put a provider secret into `ps`/tmux state.
+4. **Env allowlist not widened.** Only the `PI_` prefix is added; the provider keys stay out (§2.4)
+   and `ALLOWED_ENV_KEYS` is untouched. Pinned by a test that `PI_OFFLINE` passes and
+   `ANTHROPIC_API_KEY` still fails validation.
+5. **Docker seeding, not sharing.** Per §2.5: RO mount then copy, so refreshed OAuth tokens never
+   write back to the host; bind mounts stay excluded from `docker commit` so exports remain
+   secret-free.
+6. **Remote SSH.** `pi` mode goes through `defaultRemoteCommandForMode` and therefore
+   `buildSshConnectionArgs()`. No hand-built ssh line anywhere.
+7. **No sandbox claims.** Pi documents that it has no sandbox and no permission prompts, and that
+   extensions run with the user's full permissions. Codeman docs must say plainly that a pi session
+   can read, write and execute anything the Codeman user can, and point at Docker cases as the
+   isolation story. Do not imply the trust prompt is a safety boundary (upstream itself says it is
+   not). Worth one doc sentence: `pi auth print-api-key` / `print-bearer-token` (0.83.0) and
+   `pi auth check` (0.84.1) mean a pi session can print its own provider credentials by design;
+   isolation, again, is Docker.
+8. **Loud-vs-silent audit.** Before review, walk §2.8's silent list and confirm each site has its
+   pi branch; the loud ones the compiler already caught.
+
+---
+
+## 6. Test plan
+
+- `test/pi-mode.test.ts` (**new**, modeled on `test/antigravity-mode.test.ts`, 125 lines, no port;
+  file unchanged since 2026-08-06 so its structure remains the template):
+  `CreateSessionSchema`/`QuickStartSchema` accept a pi config; unsafe `model`/`provider`/
+  `resumeSessionId` values are rejected (`'pi; rm -rf /'` shapes); `buildSpawnCommand({ mode: 'pi', ... })`
+  emits expected flags, drops invalid ones, emits `--no-approve` for `approveProjectTrust: false`
+  and `--approve` for `true`, and skips `-c` when a `resumeSessionId` is present;
+  `defaultDockerCommandForMode('pi') === 'exec pi'` and
+  `defaultRemoteCommandForMode('pi') === 'exec "${SHELL:-/bin/sh}" -i -l -c \'pi\''`;
+  `isExternalCliMode('pi') === true`, `isAltScreenStripMode('pi') === false`; the env pair
+  (`PI_OFFLINE` accepted, `ANTHROPIC_API_KEY` rejected), mirroring antigravity-mode `:49-63`.
+- **First-ever coverage for `clampExternalCliBypassForOwner`** (still nothing in `test/` touches
+  it): cover pi's materialize branch (absent config still yields `approveProjectTrust: false` for a
+  non-granted owner; a sent `true` is forced to `false`; granted owner passes through) and, while
+  there, pin the three existing modes' behavior. Prefer exporting the helper for direct unit tests
+  over a heavier multi-user route fixture; either way it lives under `test/routes/`.
+- `test/run-mode-ui.test.ts`: extend `loadUi()`'s stub lists (welcome-button ids, mode buttons,
+  `ALL_OFF`) and add pi welcome/dropdown gating cases; note the static parser test
+  `'gates every mode the run-mode menu actually offers'` (`:433-456`) picks up the new
+  `data-mode="pi"` from index.html automatically and **fails until** `_refreshRunModeAvailability`
+  contains a quoted `'pi'`, which is exactly the regression it exists for. Add a
+  `describe('Pi quick start')` modeled on the antigravity one (`:840`) driving `runPi()` against a
+  stubbed `/api/pi/status` + `/api/quick-start`, asserting the posted body has `mode: 'pi'` and
+  **no `piConfig`**, and that the envelope is unwrapped. (The short-label assertion pattern is at
+  `:82`, `'Run AG'`.)
+- `test/render-index-html.test.ts` `:141`: the injected `window.__codemanCliAvailable` is asserted
+  with an exact `toEqual` and now carries **seven** keys (claude, opencode, codex, gemini,
+  antigravity, cloudflared, and since 1.12+ `git`), so it **must** gain the `pi` key (and the
+  resolver mock an `isPiAvailable`); its comment explains why: a dropped key silently un-gates
+  (§2.8).
+- `test/routes/system-routes.test.ts`: `GET /api/pi/status` shape, modeled on the antigravity
+  describe (`:816-838`) + resolver mock (`:84-87`); file unchanged since 2026-08-06.
+- `test/mobile-overview.test.ts`: `:375` is an exact-array `toEqual` over the run-menu modes and
+  **will fail until updated** to include `'pi'` (the second exact-array at `:366`,
+  `['claude', 'shell']`, is a gating case and stays as-is); the sibling static parser then covers
+  the new entry automatically. The no-hex-literals guard only scans `.mobile-overview*` rules, so
+  pi's `mode-pi` colors in mobile.css do not trip it.
+- `test/local-echo-codex-gating.test.ts` (§2.10): once the buffer-policy decision is confirmed in
+  E2E, add `'pi'` to the `it.each(['claude', 'gemini', 'opencode'])` lists (`:193`, `:376`) so the
+  chosen policy is pinned.
+- `test/skin-themes.test.ts`: will NOT trip (it enumerates skins, not modes); run it anyway since
+  styles.css is touched. `test/mobile-header-buttons-policy.test.ts`: trips only if a header
+  button is added; pi adds none (welcome button and run-menu rows are outside `header-right`).
+- Cron: schema-level acceptance of `agentType: 'pi'` (the service consumes `SessionMode`
+  generically; `src/cron/` is unchanged since the first draft). Known, documented degradation: the
+  readiness poll (`cron-service.ts:515`) looks for `❯`/`tokens`, which pi never prints, so cron pi
+  jobs burn the ready-poll attempts and then send anyway. Acceptable for v1; note it in
+  `docs/cron-guide.md`.
+- Sweep with `npm run test:ci`. Never bare `npm test`. No new ports needed (all new/extended suites
+  are portless).
+
+---
+
+## 7. End-to-end verification (required before COM)
+
+Unit tests passing is not evidence the mode works (pi is not currently installed on the dev box, so
+step 1 is a real step). Before shipping:
+
+1. Install pi (`npm install -g --ignore-scripts @earendil-works/pi-coding-agent`), authenticate once
+   with `/login`.
+2. `curl -sk https://localhost:3000/api/pi/status | jq` reports `available: true`, the right path,
+   and a sane `version`.
+3. Create a **throwaway** case, launch a pi session from the Run dropdown, send a prompt from the
+   browser, confirm the reply renders and scrollback survives a tab switch. Do not touch
+   `w1`/`w2`/`w3`.
+4. **Local-echo policy gate (§2.10):** on a phone profile, type into the pi editor through the
+   buffer overlay (drive with `page.keyboard.type()`, never `app.sendInput()`, and force
+   `app._localEchoEnabled = true`; headless Chromium reports touch as false) and confirm pi's
+   composer renders the flushed text correctly on Enter. If it mis-renders, flip pi to the `'off'`
+   branch in `_updateLocalEchoState` and pin that instead.
+5. Visual pass on the **default skin** (the §2.9 finding makes this the load-bearing check, not a
+   formality): run-button gradient actually renders rose (not generic claude blue), dot, tab badge,
+   welcome button, kill-menu label; then a phone profile (toolbar `!important` colors and light-skin
+   overrides are the usual regressions).
+6. Kill and respawn the session; confirm `piConfig` round-trips through `state.json` and the pane
+   comes back with the same flags. Then `/clear`-style respawn via the Respawn tab.
+7. Extended keys (§2.7): in an attached terminal, verify whether Shift+Enter inserts a newline in
+   pi's editor with and without the socket-scoped options; record the outcome in
+   `docs/pi-integration.md` either way. While attached, also flip `/settings` to the fullscreen TUI
+   and back to confirm the no-strip decision holds (§2.2).
+8. Trust model: point a throwaway case at a repo containing `.pi/extensions`, confirm the trust
+   prompt appears interactively and that a multi-user non-granted session instead launches with
+   `--no-approve` (prompt never shown, extensions not loaded).
+9. **NOT RUN in this pass — an honest gap.** Docker case with `mode: 'pi'`: rebuild the agent image with `--no-cache`, confirm `pi --version`
+   inside the container **as the `agent` user**, confirm seeded auth works and a session starts
+   (this is exactly where the antigravity Docker path broke in 1.11.2: the CLI was never installed
+   in the image).
+10. **NOT RUN in this pass — the other gap.** Remote SSH case with `mode: 'pi'`: confirm the
+    login-shell wrapper resolves the npm global bin.
+11. Only then: changeset, `COM minor` (new capability, additive to the API surface).
+
+**Verification actually performed** (2026-08-13, pi 0.84.1, isolated `CODEMAN_INSTANCE=pi-beta`
+server on :5055 with its own tmux socket and data dir): steps 1-8 pass. Highlights:
+`/api/pi/status` resolved through the **search-dir fallback** (pi installed to `~/.npm-global/bin`,
+deliberately not on PATH) and reported
+`{available:true, path:'/home/arkon/.npm-global/bin', version:'0.84.1'}`; the real spawn line came
+out as `… COLORTERM=truecolor … && pi --approve --provider anthropic --thinking high`; `piConfig`
+round-tripped through `state.json` across a **full server restart**; the trust prompt appeared for a
+case containing `.pi/extensions` + `.pi/settings.json`, and `--no-approve` suppressed it
+(`This project is not trusted. Project .pi resources and packages are ignored.`); on the **default
+`daylight-blue` skin** the toolbar Run button computed to
+`linear-gradient(135deg, rgb(190,24,93), rgb(244,114,182))` — genuinely rose and **distinct from
+claude's blue**, so the §2.9 cascade trap is avoided; and flipping `/settings` to the fullscreen TUI
+put the pane into the alt screen (`alternate_on=1`), **empirically confirming §2.2**: had pi been in
+the strip list, Codeman would have stripped that switch and corrupted the session. Steps 9-10 need a
+Docker daemon and a remote host respectively.
+
+---
+
+## 8. Effort estimate
+
+Calibrated against the real antigravity history, which is the honest baseline: the feature commit
+`26cbbe0` was 24 files, +638/-63, and it then took **four follow-up commits** (`e803186` login-shell
+routing, `292ba2c` ownership helpers, `5d28999` CLI gating incl. tests, `0d0b772` docs/installer/UI
+propagation) totaling roughly +600/-170 across ~43 file-touches to make the mode actually
+first-class. Budgeting only the feature-commit shape under-scopes by ~40%. This plan folds all four
+follow-up surfaces in from the start (login-shell routing in Phase 1, availability gating in Phases
+2-3, installer/docs propagation in Phases 4-5), so expect the full footprint in one pass:
+
+| Phase                 | Size                                                                       |
+| --------------------- | -------------------------------------------------------------------------- |
+| 1. Backend core       | ~260 lines across 9 files, one new file (resolver incl. version probe)     |
+| 2. Web layer          | ~110 lines across 4 files (incl. the clamp widening + availability inject) |
+| 3. Frontend           | ~175 lines across 10 files (enumerations + CSS in two sheets + skin block + the Brain picker option) |
+| 4. Docker + installer | ~45 lines, plus one `--no-cache` image rebuild                             |
+| 5. Docs               | one new doc, ~10 files touched                                             |
+| 6. Tests              | one new test file, 6 extended (2 of which fail loudly until updated), plus the first clamp coverage |
+
+---
+
+## 9. Out of scope, tracked as follow-ups
+
+- **A Codeman pi extension for real idle/completion events (highest value, now fully de-risked).**
+  Pi extensions are TypeScript modules with Node built-ins and npm deps available, so an HTTP POST
+  to `/api/hook-event` is trivial. The **`agent_settled`** event **shipped in 0.84.0** and is
+  documented for exactly this use case (fires only when pi will not continue on its own: after
+  auto-retries, auto-compaction and queued follow-ups; `ctx.isIdle()` is true inside the handler).
+  That is a genuine idle signal replacing output-silence heuristics, i.e. the same class of upgrade
+  hooks give Claude sessions. The bash tool exposes five env vars (`PI_SESSION_ID`,
+  `PI_SESSION_FILE`, `PI_PROVIDER`, `PI_MODEL`, `PI_REASONING_LEVEL`), injected per command. Bonus:
+  an extension can own the **`project_trust`** event (first yes/no wins, and CLI `-e` extensions
+  load *before* trust resolution), so Codeman could answer the trust prompt programmatically, a
+  cleaner mechanism than the `--approve` flag for both the single-user convenience case and the
+  multi-user deny case.
+- **Response viewer for pi.** Sessions are JSONL v3 under
+  `~/.pi/agent/sessions/--<cwd-dashed>--/<timestamp>_<uuid>.jsonl` with an `id`/`parentId` tree and
+  typed content blocks (text, image, thinking, toolCall); the cwd-derived dir name is trivially
+  computable host-side. Feasible, and it would justify flipping the Docker cred policy to share
+  `sessions/` RW like Codex.
+- **Mode-aware env allowlist.** Would let pi sessions accept provider keys without widening the
+  global list. Needs `ALLOWED_ENV_PREFIXES` to become a per-mode map plus mode context inside the
+  Zod refine.
+- **`--tools` / `--exclude-tools` / `--no-tools` / `--no-builtin-tools` read-only sessions** (plus
+  the 0.84.0 `defaultTools` setting). Real product value, needs UI.
+- **Predictive echo for pi's composer** if the §2.10 buffer decision does not hold up in practice:
+  teach `PredictiveEchoAddon` pi's composer row the way `isCodexComposerRow` handles codex's.
+- **`--mode json` / `--mode rpc`, and upstream's experimental remote-session client APIs**
+  (transport-neutral `PiClient`, CBOR protocol, Unix-socket transport, `RemoteSession` controller,
+  still unreleased as of 0.84.1). A potential non-PTY integration path, a different architecture
+  from the tmux+PTY model. Note the already-shipped breaking change to `message_update` framing
+  (delta-only): any consumer must assemble deltas between `message_start`/`message_end`.
+- **`--name` for session labels.** Blocked on shell-quoting a user string in `buildSpawnCommand`.
+
+---
+
+## 10. Risks
+
+| Risk                                                                | Mitigation                                                                     |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `pi` resolves to an unrelated binary                                | `pi --version` + semver-shape check in the resolver (§2.6); path and version shown in `/api/pi/status` |
+| Pi's TUI repaints in a way the browser terminal handles badly       | Test scrollback and repaint early (step 3 of §7); pi's default is main-screen with terminal-owned scrollback, which is the friendly case |
+| Fullscreen TUI mode (shipped 0.84.0, runtime-switchable)            | Already designed for: pi stays OUT of the strip list, so a user flipping `/settings` to fullscreen gets opencode-like alt-screen behavior, not corruption. §7 step 7 tests the flip explicitly |
+| The buffer local-echo overlay fights pi's live composer             | §2.10: explicit E2E gate (§7 step 4) with the one-line `'off'` fallback; predictive echo for pi is a tracked follow-up, not a v1 blocker |
+| Pi moves fast (pre-1.0; 9 releases in the 7 weeks before 0.84.1)    | Keep the flag surface small; every flag validated and droppable; nothing pinned in the Dockerfile beyond the `--no-cache` rebuild cadence. Live example of the hazard: `--tui-mode` went from main-only docs to released between the two drafts of this plan |
+| Docker image grows                                                  | Pi is an npm package; the layer is modest next to the ~190MB `agy` binary      |
+| Trust prompt blocks a session                                       | Narrower than feared: only fires when `.pi/settings.json`, `.pi/extensions\|skills\|prompts\|themes`, `.pi/SYSTEM.md`/`APPEND_SYSTEM.md` or `.agents/skills` exists (bare `.pi/` does not). Documented; `approveProjectTrust` is the opt-in escape hatch; multi-user forces `--no-approve` (§5.2); the `project_trust` extension follow-up removes the prompt entirely |
+| Interactive `/login` OAuth can't complete headlessly                | Document: authenticate once interactively (or seed `auth.json`); `pi auth check` verifies credentials preflight; OpenRouter's paste-the-redirect-URL flow covers remote SSH |
+| Provider auth is awkward without key prefixes in the allowlist      | `/login` writes `~/.pi/agent/auth.json` once and Docker seeds it; the mode-aware allowlist follow-up removes the friction |
+| Cron pi jobs mis-detect readiness                                   | Known degradation, documented in §6; readiness falls through after the poll budget and the prompt still sends |

docs/pi-integration.md

@@ -0,0 +1,235 @@
+# Pi (pi.dev) sessions
+
+Codeman can drive [Pi](https://pi.dev) (`@earendil-works/pi-coding-agent`, MIT) as a
+session backend, alongside Claude Code, OpenCode, Codex, Gemini and Antigravity.
+`pi` is a sixth **run mode**: its own PTY, its own tmux session, its own tab colour
+(rose). It is not a location overlay like Docker or remote-SSH cases, and it is not
+a web tab.
+
+Tracking issue: [#206](https://github.com/Ark0N/Codeman/issues/206). The design
+rationale behind each decision below lives in `docs/pi-integration-plan.md`.
+
+## Install
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+# or
+curl -fsSL https://pi.dev/install.sh | sh
+```
+
+Both installers end up going through global npm, so either one uninstalls with
+`npm uninstall -g @earendil-works/pi-coding-agent`.
+
+Codeman finds the binary via `which pi` and then the usual global-bin locations
+(`~/.local/bin`, `/usr/local/bin`, `~/.bun/bin`, `~/.npm-global/bin`, `~/bin`).
+
+**`pi` is a short, generic name**, so unlike the other CLI resolvers Codeman does
+not trust a `which` hit on its own: it runs `pi --version` once and requires
+semver-shaped output. Anything else is rejected as "not installed" and the
+rejected path is logged. Check what it resolved:
+
+```bash
+curl -s localhost:3000/api/pi/status | jq
+# { "available": true, "path": "/home/you/.local/bin", "version": "0.84.1" }
+```
+
+That endpoint carries `version` on top of the shape the sibling `/api/*/status`
+endpoints return, precisely so a misresolution is visible rather than presenting
+as "the mode just doesn't work".
+
+## Authenticate
+
+Pi supports 15+ providers. Two ways in:
+
+- **OAuth subscription login** — run `/login` inside a pi session. Six providers
+  support it: ChatGPT Plus/Pro, Claude Pro/Max, GitHub Copilot, xAI, OpenRouter
+  and Radius. Credentials land in `~/.pi/agent/auth.json` and pi refreshes them
+  itself. OpenRouter's flow accepts a pasted redirect URL, which is what makes it
+  workable over remote SSH.
+- **API keys** — exported in the environment of the **Codeman server process**.
+
+⚠️ **Provider API keys cannot be sent as per-session `envOverrides`.** Pi reads
+about 34 provider variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+`DEEPSEEK_API_KEY`, `HF_TOKEN`, `BASETEN_API_KEY`, …) that share no common prefix.
+Codeman's env allowlist is a single global list applied to every mode at once, so
+admitting bare provider keys for pi would widen the allowlist for Claude, Codex,
+Gemini and everything else too. Only the **`PI_*`** prefix was added, which covers
+every documented pi input: `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`,
+`PI_PACKAGE_DIR`, `PI_OFFLINE`, `PI_SKIP_VERSION_CHECK`, `PI_TELEMETRY`,
+`PI_CACHE_RETENTION`, `PI_SHARE_VIEWER_URL`, `PI_HARDWARE_CURSOR`,
+`PI_EXPERIMENTAL`.
+
+`pi auth check` verifies credentials before you start a long run.
+
+Note if you authenticate with a Claude Pro/Max subscription: third-party harness
+usage bills as Anthropic "extra usage" per token rather than against plan limits.
+
+## What Codeman wires up
+
+`PiConfig` (per session, persisted in `state.json`, round-trips through respawn):
+
+| Field                 | Flag                                   | Notes                                                            |
+| --------------------- | -------------------------------------- | ---------------------------------------------------------------- |
+| `model`               | `--model <v>`                          | Accepts `provider/id` and a `:<thinking>` suffix (`sonnet:high`) |
+| `provider`            | `--provider <v>`                       | `anthropic`, `openai`, `google`, …                               |
+| `thinking`            | `--thinking <v>`                       | `off`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max`              |
+| `continueSession`     | `-c`                                   | Skipped when `resumeSessionId` is set (the two conflict)          |
+| `resumeSessionId`     | `--session <v>`                        | Ids only, never paths                                             |
+| `approveProjectTrust` | `--approve` / `--no-approve` / nothing | Tri-state, see below                                              |
+
+Every value is regex-validated and **dropped** (not escaped) if it fails, because
+the result is interpolated into the pane's `bash -c "…"` command.
+
+The Run button sends **no `PiConfig` at all**: pi has no permission prompts to
+bypass, and project trust is a decision the person at the terminal makes.
+
+## What Codeman deliberately does NOT wire up
+
+- **`--api-key`.** Never. It would put a provider secret on the spawn command
+  line, visible in `ps`, tmux server state and logs. `PI_*` overrides go through
+  socket-scoped `tmux setenv` for exactly this reason.
+- **`--tui-mode`.** Pi's default main-screen TUI is the friendly case for a
+  browser terminal. The fullscreen mode (0.84.0) stays your own runtime choice via
+  `/settings`.
+- **`--name`, `--no-session`, `-p`/`--print`, `--mode json`, `--mode rpc`,
+  `--tools`/`--exclude-tools`, `-e`/`--extension`, `--skill`,
+  `--system-prompt`.** Tracked as follow-ups in the plan doc.
+
+## Permission and trust model — read this
+
+**Pi has no permission prompts and no sandbox.** There is no
+`--dangerously-skip-permissions` analog and none is needed: tools run with the
+user's own permissions, always. A pi session can read, write and execute anything
+the Codeman user can. If you need isolation, use a **Docker case** — that is the
+isolation story, here as everywhere else in Codeman.
+
+Pi's "project trust" prompt is **not** a safety boundary (upstream says so too).
+It gates *loading* repo-local `.pi/` config, extensions and skills, and
+*installing* missing project packages. It only appears when the cwd or an ancestor
+contains `.pi/settings.json`, `.pi/extensions|skills|prompts|themes`,
+`.pi/SYSTEM.md`/`.pi/APPEND_SYSTEM.md`, or `.agents/skills`. A bare `.pi/`
+directory does not trigger it.
+
+`approveProjectTrust: true` answers it with `--approve`, which means pi **loads
+and executes repository-supplied TypeScript** and runs an npm install for missing
+project packages. Treat it exactly as seriously as that sounds.
+
+**Multi-user mode:** for an owner without the privileged-command grant, Codeman
+materializes `approveProjectTrust: false` so the pane launches with
+`--no-approve` and the prompt never appears. Merely *omitting* `--approve` would
+not be a clamp, since pi's own default is to ask and the session user could just
+answer yes.
+
+Also worth knowing: `pi auth print-api-key` / `print-bearer-token` and
+`pi auth check` mean a pi session can print its own provider credentials by
+design. Isolation is Docker.
+
+## tmux extended keys (Shift+Enter)
+
+Pi's editor uses `Shift+Enter` / `Ctrl+Enter` for newline-vs-submit. Without
+extended keys, tmux collapses both into a plain `\r`. Upstream recommends:
+
+```tmux
+set -g extended-keys on
+set -g extended-keys-format csi-u
+```
+
+`extended-keys-format` needs tmux 3.5+; on 3.2–3.4 `extended-keys on` alone works
+(pi falls back to xterm `modifyOtherKeys`).
+
+Codeman's browser input path sends `\r` for submit, so basic use works
+unconfigured — what degrades is newline-in-editor, mostly when you attach to the
+pane directly (`codeman tui`).
+
+⚠️ Upstream notes the setting may need a full `tmux kill-server` to take effect.
+**Never run `tmux kill-server` on Codeman's socket** — it would kill every live
+session, `w1`/`w2`/`w3` included.
+
+**Measured (tmux 3.4, pi 0.84.1): no `kill-server` is needed.** Setting the option
+server-scoped on Codeman's own socket takes effect on the ALREADY-RUNNING server;
+the next pi session starts without the warning. Existing sessions keep the old
+setting until they respawn.
+
+```bash
+tmux -L codeman set -s extended-keys on
+tmux -L codeman set -s extended-keys-format csi-u   # tmux 3.5+ only, see below
+tmux -L codeman show-options -s | grep extended     # verify
+```
+
+On **tmux 3.4 and older, `extended-keys-format` does not exist** and the second
+line fails with `invalid option: extended-keys-format`. That is harmless — pi
+falls back to xterm `modifyOtherKeys` and `extended-keys on` alone silences the
+warning. Run the two lines independently rather than chained.
+
+Pi tells you which state it is in: an unconfigured session prints
+`Warning: tmux extended-keys is off. Modified Enter keys may not work.` in its
+startup banner, so you can verify the change by starting a new pi session.
+
+⚠️ Use `-L <socket>` and `-s`, never `-g` on your default socket, and never
+`kill-server`. Codeman does not set this for you: it is a server-wide tmux option
+and silently changing key encoding for every session of every backend is not
+Codeman's call to make.
+
+## Typing from the browser (local echo)
+
+On touch devices Codeman buffers typed characters in the `LocalEchoOverlay` and
+flushes them to the PTY on Enter. Pi gets that `'buffer'` policy, the same as
+Claude, Gemini and OpenCode.
+
+This was an explicit open question, because that policy is exactly what broke
+Codex (issues #218/#219/#220/#222): Codex's composer reacts per keystroke, so
+buffer-until-Enter starved it. **Measured against pi 0.84.1: it does not
+reproduce.** Pi's slash-command picker re-filters on the whole composer content
+rather than on per-keystroke deltas, so a one-shot flush of `/set` filters the
+picker down to `settings` identically to typing it character by character, and
+the delayed `\r` then selects it. Prose prompts flush and submit correctly too.
+
+If a future pi release changes that, the cheap fallback is one `'off'` branch in
+`_updateLocalEchoState` (terminal-ui.js); teaching `PredictiveEchoAddon` pi's
+composer row is the larger follow-up.
+
+## Docker cases
+
+The agent image (`docker/agent.Dockerfile`) installs pi in its own `RUN` step with
+`--ignore-scripts`, kept out of the shared npm block so the flag cannot change how
+the other four CLIs install. Rebuild with:
+
+```bash
+node scripts/build-agent-image.mjs --no-cache   # --no-cache is mandatory
+```
+
+Credentials are **seeded**, not shared: `~/.pi/agent/auth.json`, `settings.json`,
+`trust.json`, `models.json` and `models-store.json` are mounted read-only and
+copied into the container's own `~/.pi/agent`. So an in-container pi never writes
+refreshed OAuth tokens back to the host, and `docker commit` exports stay
+secret-free. `models.json` is in the list because it holds user-defined custom
+providers, which would otherwise silently vanish inside containers.
+
+Only those five files are seeded because `~/.pi/agent` also holds `sessions/`,
+`extensions/`, `skills/` and the installed package trees (`npm/`, `git/`), which
+on an active host is easily gigabytes.
+
+**Trade-off:** in-container pi sessions are invisible host-side, so `pi -c` inside
+a Docker case only sees that container's own history.
+
+## Remote SSH cases
+
+`pi` mode is routed through an interactive login shell
+(`exec "$SHELL" -i -l -c 'pi'`), because sshd's remote-command PATH does not
+include npm's global bin on most hosts. Per-session config and `envOverrides` do
+not cross ssh and are rejected rather than silently ignored; use the per-host
+command override instead.
+
+## Known gaps
+
+- **No idle/completion hook.** Pi has no hook system Codeman can install into, so
+  idle detection falls back to output-stabilization like the other external CLIs.
+  Pi 0.84.0 shipped an `agent_settled` extension event that is a genuine idle
+  signal; a Codeman pi extension using it is the highest-value follow-up.
+- **No response viewer.** Pi writes JSONL v3 session files under
+  `~/.pi/agent/sessions/`; nothing reads them yet.
+- **Cron jobs mis-detect readiness.** The cron readiness poll looks for `❯` or a
+  token count, neither of which pi prints, so a pi cron job burns its poll budget
+  and then sends the prompt anyway. It works; it is just slower to start.
+- **Ralph, respawn heuristics, token/CLI-info parsing and the `❯` readiness probe
+  are off** for pi, as for every external CLI.

docs/predictive-echo-plan.md

@@ -0,0 +1,143 @@
+# Predictive write-through echo for codex
+
+Zero-lag local echo for codex sessions via a second, mosh-style mode in the
+`xterm-zerolag-input` package: every keystroke goes to the PTY exactly as the
+1.12.2 overlay-disabled path did (byte-identical wire behavior), while a
+`PredictiveEchoAddon` simultaneously paints the predicted glyph at the predicted
+cell. When the real echo lands, the prediction is confirmed and its span removed
+(invisible swap: identical glyph beneath). Mispredictions drop via a mismatch
+cascade + TTL. Visual-only, self-healing.
+
+## Why this exists
+
+Issues #218/#219/#220/#222 (one root cause) forced 1.12.2 to disable the
+LocalEchoOverlay for codex: buffer-until-Enter starves codex's per-keystroke TUI
+(live slash picker, arrows editing server-side composer state, composer
+rewrap/growth, paste_burst classification). Buffer mode is structurally
+incompatible with codex; write-through prediction is the only echo mode that
+can coexist with it.
+
+## The reconciliation lesson (do not regress this)
+
+`docs/local-echo-overlay-plan.md` ("What NOT to Do") documented that matching
+predictions against the raw output STREAM fails against Ink/TUI full-line
+redraws. This design reads the parsed terminal BUFFER instead (cells after
+xterm's parser ran), which converges to the same cells no matter how the bytes
+arrived. The Phase 0 recordings prove the point twice over: tmux converts
+codex's full-line redraws into minimal in-place deltas (an echo arrives as
+`e\x1b[K\x1b[20;80H...`), and codex itself paints word gaps with ECH+cursor-forward
+instead of spaces. Stream matching can never survive that; buffer diffing does
+not care.
+
+## Phase 0 measurements (codex-cli 0.147.0 via tmux, 100x30, 2026-08-09)
+
+Recorded with `scripts/dev/record-codex-frames.mjs` (production pipeline:
+codex inside tmux `status off`, chunks passed through the same full strip
+`session.ts _handleTerminalOutput()` applies to codex mode). Fixtures in
+`packages/xterm-zerolag-input/test/fixtures/codex/`; replay/measure with
+`scripts/dev/analyze-codex-frames.mjs <fixture>`.
+
+| Question              | Measured answer                                                                                                                                                              |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Composer signature    | Cursor row starts `"› "` (U+203A + space), text begins col 2. Present when empty (placeholder), while typing, and while the slash picker filters. `CODEX_COMPOSER_ROW_RE = /^› /` |
+| Composer text color   | Plain default foreground, zero SGR around echoed chars. Span `foregroundColor` default (theme fg) is an exact match                                                            |
+| Placeholder           | Cycling hint text ("Use /skills...", "Improve documentation in @filename", ...) rendered AT the cursor cell. First prediction lands over placeholder glyphs: covered by the snapshot + cursor-advance rules |
+| Wrap                  | Word-wrap near `cols - 2`; continuation rows are indented 2 spaces WITHOUT `› `. The gate therefore suppresses predictions on wrapped lines: deliberate fallback to real echo, wrap was the #220 ghost zone. `edgeMarginCells = 4` |
+| Modal (trust dialog)  | Cursor parks on `"  Press enter to continue"`: no `› ` prefix, gate false, zero predictions painted while keystrokes still reach the PTY (the ghost eliminator)                 |
+| Streaming             | Error/reconnect bursts render above a re-rendered composer that keeps the `› ` signature; end-of-frame cursor parks at the insertion point (col 2 of the composer row). Confirms the cursor-advance confirm rule and the no-drop-on-baseY rule |
+| Echo shape under tmux | tmux emits minimal deltas for simple echoes and full repaints for busy frames; both converge in the parsed buffer                                                              |
+| Slash picker          | Picker rows render below; the cursor row keeps the composer signature and advances per filter char, so predictions stay active while filtering (#222 surface)                 |
+
+Constants decided at the Phase 0 gate: `CODEX_COMPOSER_ROW_RE = /^› /`,
+`ttlMs = 1000`, `maxPending = 32`, `cursorGraceMs = 150`, `edgeMarginCells = 4`,
+span colors = theme defaults, `underlinePredictions = false`.
+
+## Algorithm
+
+See `PredictiveEchoAddon` in
+`packages/xterm-zerolag-input/src/predictive-echo-addon.ts`. Summary of the
+rules and why each exists:
+
+- **State**: ordered `PredictionRecord[]` (`seq`, `char`, `width`, cumulative
+  `offsetCells`, `snapshot` of the cell at predict time, `sentAt`,
+  `mismatches`), plus a run `_anchor {row, col}` captured when the outstanding
+  count goes 0 -> 1. Positions are FIXED at predict time; confirmation deletes
+  spans and never re-lays-out, so partial confirmation causes zero jitter.
+- **predictChar(ch)** runs an inline reconcile first and re-anchors whenever
+  outstanding drains to zero (absorbs the echo-landed-between-keystrokes race).
+  Guards: dims present, cursor numbers present, `viewportY === baseY`,
+  `predictWhen` gate, single codepoint >= 0x20 (not 0x7f), width <= 2,
+  `maxPending`, edge margin. Returns false = suppressed; the consumer sends the
+  keystroke regardless.
+- **Coordinate base is `baseY`**: xterm's `cursorY` is baseY-relative, so
+  absolute buffer line = `baseY + row`. `viewportY` would only coincide while
+  the scrolled-to-bottom guards hold; the addon never relies on that.
+- **reconcile()** (debounced `onWriteParsed` microtask, inline in predictChar,
+  TTL timer): clears everything when scrolled up; off-anchor-row cursor
+  tolerated for `cursorGraceMs` then clears; PREFIX-ONLY confirm loop requiring
+  cell match AND cursor advanced past the record (prevents false confirms
+  against placeholder glyphs and makes identical in-place tmux repaints a
+  no-op); TWO-PASS mismatch rule (a cell that is neither snapshot nor predicted
+  char must persist across two passes before cascading the drop: a half-parsed
+  row on pass N is fully redrawn a few ms later); TTL drop of the stale suffix.
+- **No drop on baseY change**: codex streams push lines to history while the
+  composer stays viewport-pinned; predictions are row-relative to the pinned
+  composer and remain valid (measured above).
+- **Anchor hold** (added by the independent post-build review): after any wire
+  input whose cursor effect the display has not shown yet (backspace with
+  nothing outstanding = deleting echoed text, every 'clear'-classified input,
+  an IME/plain-paste 'text' commit, and the bypass send paths), new
+  predictions are suppressed until the next PARSED write. Anchoring on the
+  stale cursor painted ghosts one cell off ("tehh" on backspace-then-retype
+  within RTT), blank-neutral and therefore TTL-lived. Worst case is exactly
+  one unpredicted keystroke: its own echo is a write, which releases the hold.
+- **predictBackspace()** pops the newest outstanding record (informational
+  return; the consumer forwards `\x7f` unconditionally). Deleting already-echoed
+  text renders at RTT in v1.
+- **CJK/wide**: 2-cell spans, stacking by cumulative visual width, leading-cell
+  confirm. In Codeman, IME input never reaches the hook (`window.cjkActive`
+  returns from onData first); package support exists for other consumers.
+
+## Integration map (Codeman)
+
+- Policy: `_localEchoPolicy` (`'buffer' | 'predict' | 'off'`) computed at the
+  end of `_updateLocalEchoState()`; codex + `localEchoEnabled` -> `'predict'`
+  while `_localEchoEnabled` stays false (every 1.12.2 consumer unchanged).
+- onData hook sits between the buffer block and Normal Mode, classifies via
+  `classifyPredictInput()` (pure, on `window.CodemanTerminalInput`), never
+  returns, try/catch-wrapped: the wire path below is byte-identical with the
+  predictor active, absent, or throwing.
+- Composer gate: `isCodexComposerRow()` set via `setPredictWhen()` at
+  construction (the vendor footer stays package-agnostic).
+- Second vendor bundle `vendor/xterm-predictive-echo.js` (postinstall + build);
+  the zerolag bundle build command is untouched and its output byte-identical.
+  Missing/broken bundle = plain 1.12.2 echo (`typeof PredictiveEchoOverlay ===
+  'undefined'` guard).
+- Prediction clears on: tab switch, SSE reconnect init, `insertTerminalText`,
+  `clearTerminalInput`, voice send, keyboard-accessory `sendKey`, resize, skin
+  and font changes re-read style via `refreshFont()`.
+
+## Risk register
+
+Eliminated structurally: other-mode regression (zero edits to buffer
+addon/branches, byte-identical existing bundle, policy-matrix + byte-identity
+tests); bundle breakage (separate bundle, graceful degradation); wire
+corruption (no-return fall-through + try/catch + byte-identity pins at vm and
+E2E level); modal ghosts (measured predictWhen gate); false confirms
+(cursor-advance rule); mid-parse flicker drops (two-pass rule); wrap
+misplacement (edge margin + continuation-row gate fallback + off-row grace).
+
+Accepted residuals (visual-only, self-healing <= ttlMs, kill-switchable via
+`localEchoEnabled` per device): no predictions on wrapped continuation lines
+(gate false there, deliberate); brief dropout during composer growth; DOM-span
+vs WebGL glyph rendering can differ subtly (same trade-off as the buffer
+overlay, same font recipe); typing during an unsynchronized half-frame can
+mis-anchor one run (mismatch/TTL cleans within 1s).
+
+## Future work
+
+RTT-adaptive TTL; mosh-style confidence gating (paint only after the link
+proves laggy); predicted backspace into echoed text; predict mode for shell
+prompts; unifying the small font/container duplication between the two addons
+once predict mode has proven out; continuation-line prediction behind a
+smarter composer-extent detector.

docs/readmymind-plan.md

@@ -0,0 +1,140 @@
+# Read My Mind (design)
+
+A 🧠 button that predicts the prompt you were about to type. Codeman keeps a per-case **intent profile** (your stated goals plus the real prompts you recently sent), feeds it and the live pane tail to a one-shot `claude -p`, and shows the predicted next prompt in a plan-mode-style approval dialog: **Send** / **Rethink** (with an optional steer note) / **Insert** (drop it on the composer to edit) / **Dismiss**. It is also a skill surface: the agent can read the intent profile, record intentions, and request a prediction over the HTTP API. Suggestions are **never auto-sent**; the human click is the boundary.
+
+## UX flow
+
+1. User hits 🧠 (desktop header button; phone: keyboard-accessory key).
+2. Modal opens with a spinner, then the top suggestion in an editable single-line field, rationale below it, up to 2 alternates as tappable rows.
+3. Buttons: **Send** (submits with `\r`), **Insert** (sends without `\r`, so the text sits unsubmitted on the CLI composer for editing, a documented mechanism), **Rethink** (optional free-text steer, e.g. "no, I meant the mobile bug", re-runs with the rejected suggestions included), **Dismiss**.
+4. Accepted prompts flow back into the intent history like any other sent prompt, so the profile self-corrects.
+
+## Scope (v1)
+
+- Claude mode only (capture rides Claude transcripts; external CLIs have no transcript watcher). Mirrors the approvals-inbox scoping.
+- Opt-in: `readMyMindEnabled`, synced, default **OFF**. While OFF: no capture, no UI surfaces. Privacy first, and every press costs real tokens.
+- One prediction in flight per session; the button disables while checking.
+- Sync request/response (the predictor takes 5-30s; agent-wait long-polls already hold requests longer). No new SSE events in v1.
+
+## Data model
+
+Per case, not per session: intentions outlive `/clear` and respawns.
+
+```ts
+interface IntentProfile {
+  key: string;              // sha256(owner + ':' + realpath(workingDir)).slice(0, 16)
+  workingDir: string;
+  updatedAt: number;
+  goals: string;            // freeform markdown, user/agent editable, ≤ 8 KB
+  recentPrompts: { ts: number; sessionId: string; text: string }[]; // FIFO cap 50, each ≤ 500 chars
+}
+```
+
+Storage: `dataPath('intents.json')`, written mode 0600 (prompts can contain secrets; same posture as `users.json`). Never enters the `/api/search` index. Add to the CLAUDE.md State Files list.
+
+## Intent capture
+
+**Source: the session transcript, not the input paths.** `POST /api/sessions/:id/input` sees only programmatic input, and the WS channel delivers raw keystrokes (`session.write(msg.d)`), so neither yields clean submitted prompts. Claude's own JSONL transcript records every user turn as structured text, and `transcript-watcher.ts` already tails it. Add a `userPrompt` event there:
+
+- Emit for `type: 'user'` entries whose content is a string or contains a text block; skip entries that are only `tool_result` blocks (tool results are wrapped as user messages).
+- Skip `<command-name>` / `<local-command-stdout>` tagged entries (local slash-command echo, not intent).
+- Skip texts < 3 chars (menu digits, Esc artifacts), truncate to 500, drop consecutive duplicates ("continue" spam from auto-resume stays but dedupes).
+
+`IntentStore` (new `src/intent-store.ts`, pure core + IO wrapper, in the style of `session-order.ts`) subscribes via session wiring, gated on the setting resolved from **merged** settings per the partial-PUT rule.
+
+## Context assembly (how the mind reading actually works)
+
+The quality of the suggestion is decided before the model ever runs, by what we put in front of it. A new pure function `buildPredictionContext()` (in `src/readmymind-context.ts`, unit-testable with fixtures, no IO of its own; collectors inject their data) assembles a budgeted, priority-ordered prompt from every signal Codeman already has:
+
+| # | Source | What it contributes | Cap |
+| - | ------ | ------------------- | --- |
+| 1 | **Pending dialog** (approvals-inbox store, when present) | If the session is sitting on an AskUserQuestion / permission / idle prompt, the honest "next prompt" is an *answer*. The dialog text + parsed options go in first and the model is told to answer it. | 2 KB |
+| 2 | **User goals** (`goals` from the intent profile) | The only fully-trusted statement of what the user wants. Highest authority in the trust ranking below. | 8 KB |
+| 3 | **Last assistant turn** (transcript, not the pane) | Assistant replies usually *end* with the fork in the road ("Want me to X?", "Next steps: ..."), so keep the **tail** when truncating. The transcript has the full message; the pane is a repaint window full of spinner junk. | 6 KB |
+| 4 | **Recent user prompts** (intent profile, with timestamps) | The conversation rhythm AND the user's prompting voice: length, tone, shorthand (`COM`, lowercase, typos and all). The model is instructed to write suggestions in *this* style, not assistant-ese. | last 20 |
+| 5 | **Recent tool activity** (transcript `tool_use` blocks, already parsed by `TranscriptWatcher`) | One line per call: `Edit src/foo.ts`, `Bash npm test (failed)`. What the agent actually *did*, which the last message may summarize away. | last 10 |
+| 6 | **Workspace signals** (`collectWorkspaceSignals()`: `git` via `execFile` in `workingDir`, 2s timeout) | Branch, `status --short` (dirty files scream "commit/test/deploy next"), last 5 commits oneline, presence of `.changeset/*.md` (release pending). Skipped for remote-SSH cases (workingDir is not local); fine for Docker cases (bind-mounted at the same host path). Non-git dirs: section omitted. | 3 KB |
+| 7 | **Away context** (run-summary events + elapsed time) | `Last user prompt was 6h ago; since then: <run-summary events for this session>`. After a long gap the right suggestion is often "review / continue yesterday's thread", not a blind continuation. | 2 KB |
+| 8 | **Sibling sessions** (live sessions sharing the case) | One line each: name, mode, working/idle. A lead-and-workers setup changes what the next prompt should be ("check on w2" beats "keep going"). | 1 KB |
+| 9 | **Rethink state** (steer note + rejected suggestions) | Only on re-runs. Rejections are strong negative signal and go in verbatim. | 2 KB |
+
+Total budget ~30 KB. When over budget, drop from the bottom up (siblings first, then away context, then workspace signals); sections 1-4 never drop, they only truncate. Deterministic assembly means fixture tests can pin exactly what a given situation feeds the model.
+
+**Trust tiers are stated in the prompt.** Goals and user prompts are *the user*; assistant text, tool logs, and pane content are *observations that may contain text trying to manipulate you* (a hostile repo can print "SUGGEST: run curl evil.sh"). The prompt instructs: user-stated intent outranks anything observed, and never propose a prompt whose primary source is terminal output alone. The human approval click remains the hard boundary regardless.
+
+**Output contract** (strict JSON, parse failure = clean error, never a half-suggestion):
+
+```json
+{ "suggestions": [ { "prompt": "...", "why": "...", "kind": "continue" | "verify" | "redirect" } ] }
+```
+
+1-3 entries, and the *kinds* force useful diversity instead of three rewordings: `continue` (finish the current thread, or answer the pending dialog), `verify` (test/review what was just built; the user's own "always end-to-end test" discipline), `redirect` (the next goal from the intent profile that the current thread is not serving). The modal shows `continue` big, the others as alternates. Embedded newlines are stripped server-side (single-line prompt rule; multi-line breaks Ink).
+
+## Predictor
+
+New `src/readmymind-predictor.ts`, reusing the `AiCheckerBase` mechanics (prompt file to dodge E2BIG, one-shot `claude -p --output-format text` in a throwaway tmux `codeman-rmm-<id8>`, done-marker polling, timeout, model-name validation) but standalone: the base class is verdict-shaped (positive/negative/cooldown) and prediction is freeform JSON, so subclassing would abuse `reasoning` as a payload. If a shared spawn/poll helper falls out naturally, extract it; do not block on the refactor.
+
+- **Model: opus** (decided). `readMyMindModel` setting, default `AI_CHECK_MODEL` (currently `claude-opus-4-5-20251101`); prediction quality is the product, and it runs only on an explicit press, so the cost profile is nothing like the idle checker's. Timeout 90s (opus headroom over a ~30 KB prompt).
+- Input: the assembled context above. The predictor itself stays dumb: text in, JSON out; all intelligence about *what to include* lives in the testable assembler.
+
+## API (new `src/web/routes/readmymind-routes.ts`)
+
+Normal authed API, `ApiResponse` envelope, Zod schemas in `schemas.ts`, ownership via `findSessionOrFail` (the profile key derives from the session's owner + workingDir, so multi-user scoping is structural):
+
+- `GET /api/sessions/:id/intent` → the session's `IntentProfile`.
+- `PUT /api/sessions/:id/intent` body `{ goals }` (bounded) → update goals. Used by the modal's edit view and by the agent skill ("record that the user is working toward X").
+- `DELETE /api/sessions/:id/intent` → forget everything for this case (the modal's "Forget" affordance).
+- `POST /api/sessions/:id/readmymind` body `{ steer?, rejected? }` → `{ suggestions }`. 409 `INVALID_STATE` while a prediction is already running for the session; claude-mode sessions only (400 otherwise, mirroring wait-signal gating).
+
+## Frontend
+
+New module `readmymind-ui.js` (@loadorder 11.3, after panels-ui.js), prettier-formatted.
+
+- **Desktop**: header button `btn-readmymind`, default-hidden via marker class `btn-readmymind--hidden` (the `!important` display rules require the marker-class pattern), shown by `applyHeaderVisibilitySettings()` when the setting is ON. Off phones per `test/mobile-header-buttons-policy.test.ts`.
+- **Phone**: a 🧠 key on the keyboard accessory bar (that bar is where input helpers live, and phones are where typing hurts most). Opens the same modal. Modal z-index respects the ≤768px layer rules (1300+).
+- **Send** goes server-side: `POST /api/sessions/:id/input` with `\r` appended. Deliberately NOT the browser keystroke path, so the `sendEnterKey` / local-echo-overlay trap never applies (the modal is UI chrome, not terminal typing). **Insert** is the same POST without `\r`.
+- i18n strings registered (en + zh-CN); suggestion text itself carries `data-i18n-skip`.
+
+## Skill integration
+
+The user-facing promise: the button is also a skill. Extend `skills/codeman`:
+
+- New section "Read My Mind: intent + prediction" with the three intent verbs (read profile, append/replace goals, predict) and the guard notes (single-line prompts, never auto-send to another session without the user asking).
+- Update `reference/endpoints.md` (the endpoints.md drift test pins this).
+- The auto-injected case copy heals via the existing marker-owned `applyAgentSkill` mechanism; nothing new needed there.
+
+Agent use cases this unlocks: a lead session records intentions as the user states them ("remember: shipping 1.16 is the goal"), and a returning user gets a prediction grounded in what the agent knew, not just raw prompt history.
+
+## Security / privacy
+
+- **The human gate is the injection mitigation**: pane output (attacker-influenceable) flows into the predictor, so its output is only ever *proposed*, rendered as text (`textContent`), and sent solely by an explicit user click. No auto-send path exists, including for the skill.
+- Intent data: 0600 file, bounded fields, per-owner keys, endpoints ownership-checked, excluded from search, cleared via DELETE.
+- Predictor spawns with the user's own credentials exactly like the AI idle/plan checkers; model name shell-validated the same way.
+- Setting OFF stops capture immediately; existing data stays until DELETE (explicit, not silent).
+
+## Tests
+
+- `test/intent-store.test.ts`: key derivation, caps/FIFO, consecutive-dupe skip, tag/tool_result filtering fixtures, 0600 mode, multi-user key separation.
+- `test/readmymind-context.test.ts`: fixture scenarios pinning the assembled prompt: pending-dialog-first ordering, tail-keeping truncation of the assistant turn, budget drop order (siblings before workspace signals), remote-case git skip, trust-tier framing present, rejected suggestions included only on rethink.
+- `test/readmymind-predictor.test.ts`: strict JSON parse, garbage output → error result, newline stripping, `kind` validation, rejected-suggestions threading into the prompt.
+- `test/routes/readmymind-routes.test.ts` (`app.inject`): CRUD round-trip, predict with a stubbed predictor, 409 while in flight, non-claude 400, ownership 404, Send/Insert byte assertions via the test-PTY echo (`\r` present vs absent).
+- Transcript capture: extend the transcript-watcher fixtures with user-turn entries.
+
+## Phases
+
+1. **Intent store + capture + intent endpoints + skill docs.** Immediately useful to agents even before any UI exists.
+2. **Context assembler + predictor + predict endpoint + desktop button/modal.** The feature as pitched. The assembler ships with all collectors it can serve from day one (transcript, intent, git, run-summary, siblings); the approvals collector activates when PR #245 lands.
+3. **Phone accessory key, rethink steering, alternates row.** Part 1 (shipped): the alternates row (tappable, swap into the field without losing edits; Rethink rejects the whole shown set), the phone 🧠 keyboard-accessory key (both bar templates, `rmm-enabled` marker class on the bar), and a phone-sized modal (small dialog, not full-screen). Part 2 (shipped): rethink steering, the free-text steer note under the suggestions, sent as `steer`, visible whenever Rethink is live (ready and empty-result phases), cleared on each open; the empty-result copy points at the note, and the footer buttons moved to the styled `btn-toolbar` convention (the bare `btn btn-*` classes they shipped with match no CSS in this codebase and rendered as unstyled UA buttons).
+4. Explicitly later: proactive predict-on-idle (ghost suggestion chip), auto-compaction of `recentPrompts` into `goals` via a cheap model, codex/gemini capture, cross-case "global" intent.
+
+## Open questions
+
+- Should Rethink's rejected-suggestion memory persist across modal closes, or reset each open?
+- Is a composer-adjacent placement (next to the toolbar Run controls) better than the header for discoverability?
+- Pending-dialog input (source #1) consumes the approvals-inbox store (PR #245, merged): the phase-2 collector reads pending items directly from `src/approval-inbox.ts`.
+
+## Docs
+
+- CLAUDE.md: Key Patterns entry, State Files (`intents.json`), frontend load order, route count.
+- `docs/api-reference.md`: four endpoints (additive under the 0.9.x contract).
+- `skills/codeman/reference/endpoints.md`: new rows (drift-test enforced).

docs/readmymind.md

@@ -0,0 +1,108 @@
+# Read My Mind
+
+Codeman's per-case memory of what you are trying to accomplish, and the 🧠 button that turns it into a predicted next prompt. Each case gets an **intent profile**: a freeform `goals` text (written by you or your agent) plus the prompts you actually submitted, captured automatically while the feature is on. Pressing 🧠 feeds that profile and the live session signals to a one-shot model call and shows the predicted prompt for you to send, edit, or rethink. Nothing is ever sent to a session automatically. Design doc: [`readmymind-plan.md`](readmymind-plan.md).
+
+## What it does
+
+- Captures the prompts you submit in Claude sessions into a per-case history (50 most recent, bounded).
+- Lets you (or your agent) record explicit goals per case.
+- Predicts your next prompt on demand (the 🧠 header button, or `POST .../readmymind` for agents): the suggestion arrives in a modal with Send / Insert / Rethink / Dismiss.
+- Exposes the profile over the HTTP API, and to agents through the `codeman` skill, so an agent can ground its work in what you actually want instead of guessing from the last screenful.
+
+## Turning it on
+
+App Settings → Header & Panels → Cross-session features → **Read My Mind** (synced setting `readMyMindEnabled`, default **OFF**). It gates everything: capture, the header button, and nothing shows anywhere while it is off. The API equivalent:
+
+```bash
+curl -sk -X PUT https://localhost:3000/api/settings \
+  -H 'Content-Type: application/json' \
+  -d '{"readMyMindEnabled": true}'
+```
+
+Add `-u user:password` if your install has `CODEMAN_PASSWORD` set, and drop `-k`/use `http://` for a plain-HTTP dev server. Turning it OFF stops capture immediately; existing profiles stay until you delete them (below).
+
+## The 🧠 button
+
+On a Claude session, press the brain button in the header (desktop) or the 🧠 key on the keyboard accessory bar (phones and tablets; it appears when the setting is on). Codeman assembles everything it already knows: your goals, your recent prompts (with your voice: length, tone, shorthand), the tail of the last assistant reply, recent tool activity, git state (branch, dirty files, pending changesets), how long you have been away and what happened meanwhile, sibling sessions in the same case, and any dialog the session is currently waiting on. A one-shot model call (opus by default, `readMyMindModel` to override) turns that into 1-3 suggestions; the top one lands in an editable field with its rationale, and the others render as tappable alternate rows: tap one to swap it into the field (edits you already made are kept on the row you leave).
+
+- **Send** submits it to the session (with Enter).
+- **Insert** drops it on the CLI composer *without* Enter, so you can edit it in the terminal before sending.
+- **Rethink** re-runs with everything shown (the field and the alternates) recorded as rejected. An optional steer note below the suggestions ("no, I meant the mobile bug") rides along as your own words, the highest-authority signal the predictor gets; it stays in the field across re-runs until you clear it or reopen the modal.
+- **Dismiss** closes; nothing happens.
+
+A prediction takes 5-90 seconds and costs real tokens; one runs per session at a time. If the session is sitting on a permission/question dialog, the suggestion is usually an answer to that dialog: that is intentional.
+
+**Security note**: the prediction reads observable content (assistant output, tool logs, git output) which a hostile repo could try to steer. The predictor is told user-stated intent outranks anything observed, and, more importantly, a suggestion is only ever *proposed*: your click is the boundary. No auto-send path exists, including for agents.
+
+## What gets captured, exactly
+
+Capture reads the Claude session transcript, not your keystrokes: when a user turn lands in the transcript, its text is folded into the case's profile. Filters applied on the way in:
+
+- **Claude-mode sessions only.** Shell, OpenCode, Codex, Gemini, Antigravity, and Pi sessions are never captured (they have no transcript watcher).
+- Tool results, local slash-command echo (`/model` and friends), system wrappers, and interrupt markers are skipped.
+- Entries shorter than 3 characters are skipped (menu digits, Esc artifacts).
+- Consecutive duplicates collapse (auto-resume's "continue" spam counts once per run).
+- Each prompt is stored as one line, truncated to 500 characters; the history caps at 50 prompts FIFO.
+
+Because the transcript path arrives via Claude Code hooks, capture needs hooks to reach the server, the same condition as hook-based idle detection. Docker cases against a loopback-only server need `CODEMAN_DOCKER_BRIDGE_HOOKS=1`; remote-SSH cases do not capture.
+
+## What is never captured
+
+- Anything while `readMyMindEnabled` is OFF (capture is not retroactive).
+- Terminal output, keystrokes, passwords typed into shells: only submitted Claude prompts are read.
+- Nothing leaves the machine beyond the model call you explicitly trigger, and profiles are never fed into `/api/search`.
+
+## Where it lives, and how to wipe it
+
+Profiles live in `~/.codeman/intents.json`, written atomically at mode 0600 (captured prompts can contain secrets). The file is per Codeman instance. Keys derive from owner + the case's resolved working directory, so profiles survive `/clear`, respawn cycles, and session churn, and in multi-user mode two owners of the same directory get separate profiles.
+
+Forget one case: `DELETE /api/sessions/:id/intent` (below). Forget everything: stop the server and delete `~/.codeman/intents.json`.
+
+## The API
+
+Four endpoints, session-scoped so ownership is enforced by the session itself (`/api/v1/` aliases work too; full spec in [`api-reference.md`](api-reference.md)):
+
+```bash
+# Read the profile for a session's case
+curl -sk https://localhost:3000/api/sessions/$SID/intent | jq '.data.intent'
+
+# Record goals (REPLACES the text: read + merge if you want to append)
+curl -sk -X PUT https://localhost:3000/api/sessions/$SID/intent \
+  -H 'Content-Type: application/json' \
+  -d '{"goals":"ship 1.17; then mobile polish"}'
+
+# Forget the case
+curl -sk -X DELETE https://localhost:3000/api/sessions/$SID/intent
+
+# Predict the next prompt (claude-mode only; takes 5-90 s)
+curl -sk -X POST https://localhost:3000/api/sessions/$SID/readmymind \
+  -H 'Content-Type: application/json' -d '{}' | jq '.data.suggestions'
+```
+
+A case with nothing recorded answers an empty profile with `updatedAt: 0`; reads never persist anything. Goals cap at 8192 characters and the schema is strict, so unknown fields or over-long goals answer `400 INVALID_INPUT`. A session you do not own answers `404 NOT_FOUND`, indistinguishable from a nonexistent one. Predict answers `{ suggestions: [{ prompt, why, kind }], durationMs }` (`kind`: `continue` / `verify` / `redirect`), `409 CONFLICT` while one is already running, `400 INVALID_INPUT` on non-claude sessions, and `502 OPERATION_FAILED` when the model produced no usable JSON. The rethink flow passes `{"steer":"…","rejected":["…"]}`.
+
+## For agents (the skill)
+
+The `codeman` agent skill documents the same verbs (SKILL.md §3 plus `reference/endpoints.md`), with the ground rules: read the profile to understand what the user wants, record goals the user actually stated, merge instead of blind-writing (PUT replaces), never delete a profile unprompted, and never send a predicted suggestion into a session unless the user asked. It is the user's memory, not the agent's.
+
+## What comes next
+
+Explicitly later: proactive predict-on-idle, auto-compaction of the prompt history into goals, non-Claude capture. See the phases section of [`readmymind-plan.md`](readmymind-plan.md).
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+| ------- | ----------- |
+| No 🧠 button in the header | `readMyMindEnabled` is OFF (App Settings → Header & Panels → Cross-session features), you are on a phone (there it is a key on the keyboard accessory bar instead, visible while typing), or the active session is not claude-mode |
+| Prediction feels generic | The profile is thin: record goals (PUT or ask your agent to), and let capture accumulate a few real prompts first |
+| "A prediction is already running" (409) | One per session at a time; wait for the current one (up to 90 s) |
+| Prediction fails (502) | The model returned no usable JSON, or the CLI could not start; retry. Check `readMyMindModel` if you overrode it |
+| Profile stays empty although I am prompting | `readMyMindEnabled` was OFF at the time (capture is not retroactive), the session is not claude-mode, or hooks are not reaching the server (Docker case on a loopback bind without `CODEMAN_DOCKER_BRIDGE_HOOKS=1`, or a remote-SSH case) |
+| Short answers I typed are missing | Entries under 3 characters are filtered by design (menu digits, Esc artifacts) |
+| My goals text vanished after an agent wrote to it | PUT replaces the whole text; the skill tells agents to read + merge, but a blind write wins. Re-state the goals; consider phrasing them in the session so capture keeps the evidence |
+| Two profiles for what I think is one case | Different owners in multi-user mode, or genuinely different directories; paths are realpath-resolved, so symlink spellings converge but distinct checkouts do not |
+| `400 INVALID_INPUT` on PUT | Goals over 8192 chars, or an extra field in the body (strict schema) |
+
+## Where the code lives
+
+`src/intent-store.ts` (store + pure helpers, singleton), the `transcript:user_prompt` event in `src/transcript-watcher.ts`, capture wiring in `src/web/server.ts` (`captureIntentPrompt`), context assembly in `src/readmymind-context.ts` (pure) + `src/readmymind-collectors.ts` (transcript tail + git IO), the predictor in `src/readmymind-predictor.ts`, routes in `src/web/routes/readmymind-routes.ts`, schemas in `src/web/schemas.ts`, frontend in `src/web/public/readmymind-ui.js`. Tests: `test/intent-store.test.ts`, `test/readmymind-context.test.ts`, `test/readmymind-collectors.test.ts`, `test/readmymind-predictor.test.ts`, `test/routes/readmymind-routes.test.ts`, and the capture cases in `test/transcript-watcher.test.ts`.

docs/reliable-input-delivery.md

@@ -50,13 +50,47 @@ each `(clientId, seq)` at most once, so a resend can't type the prompt twice.
   last-applied is seen. A replayed/lower seq returns `false`. Bounded MRU map
   (`MAX_INPUT_DEDUP_CLIENTS = 256`).
 - **WS route** (`ws-routes.ts`) — parses optional `cid`/`seq` on `{t:'i'}`; applies
-  via `shouldApplyInput` (skips a duplicate, still ACKs with `{t:'ia',seq}` so the
-  client drops it). Untagged frames apply unconditionally (no behavior change).
+  via `shouldApplyInput`. An applied frame is ACKed with `{t:'ia',seq}`; a duplicate is
+  ACKed as `{t:'ia',seq,dup:true,last:<watermark>}`, where `last` is the server's
+  highest applied seq for that `clientId` (`Session.lastInputSeq`). The client drops
+  the record either way, and on `dup` it lifts its own counter to `last` first and
+  re-sends a FIRST-attempt record (a retry being called a duplicate is the mechanism
+  working: the original landed). Without `last`, a tab killed between a send and the
+  persisted counter write came back counting BELOW the server's watermark, and every
+  later keystroke was dropped-but-ACKed: a silently dead terminal a reload could not
+  fix, since the stale counter was restored from localStorage too. The client now
+  persists the counter synchronously on every send for the same reason. Untagged
+  frames apply unconditionally (no behavior change).
 - **POST route** (`/api/sessions/:id/input`) — optional `seq`/`clientId` in
   `SessionInputWithLimitSchema`; a deduped duplicate returns 200 without writing
   (the 200 is the client's ACK). `curl`/legacy callers omit the fields and always
   apply.
 
+## Oversized input (issue #484)
+
+Delivery has a third outcome besides "applied" and "retry": **refused for good**.
+Both transports refuse a frame longer than `MAX_INPUT_LENGTH` (64 KiB,
+`src/config/terminal-limits.ts`; the POST schema uses the same constant). Before
+#484 the client treated that like a transient failure, so an oversized paste sat
+at the head of the queue, was re-sent every 2 s forever, blocked every later
+input for the session, and came back from localStorage on each reload.
+
+- `_sendInputAsync()` splits a paste over the frame limit into in-limit frames
+  (`CodemanInputLimit.split`, constants.js, never cutting a surrogate pair). They
+  go out in seq order, so the PTY sees one contiguous stream. A paste over
+  `PASTE_MAX_CHARS` (1 MiB), or an oversized `useMux` write (line-oriented, never
+  split), is refused with a toast and never queued.
+- The WebSocket answers an oversized sequenced frame with
+  `{t:'ia', seq, err:'too_large', max}`; the client drops it with a toast. A
+  client that predates `err` reads it as a plain ACK and drops it too.
+- The POST drain drops a frame answered `400`/`413` (`401`/`403` stay transient:
+  an expired login delivers once the user signs in again).
+- `_loadReliableState()` prunes persisted frames over the limit, so a queue
+  poisoned by an older build heals on the first load after upgrading.
+- ⚠️ The frontend limit (`INPUT_FRAME_MAX_CHARS`) and the composer's
+  `COMPOSER_INPUT_FRAME_LIMIT` must equal `MAX_INPUT_LENGTH`; pinned by
+  `test/input-size-limit.test.ts`.
+
 ## Known limitation
 
 Dedup state is in-memory on the server. A **server restart** between a write and
@@ -70,3 +104,5 @@ across the narrow restart window.
   semantics (monotonic, per-client, gap-tolerant, eviction-safe).
 - `test/routes/session-routes.test.ts` — POST `/input` applies a tagged
   `(clientId, seq)` once on redelivery; untagged input always applies.
+- `test/input-size-limit.test.ts`: one input limit on both sides, frame
+  splitting, and dropping (never retrying) a frame refused for good (#484).

docs/remote-sessions.md

@@ -1,7 +1,7 @@
 # Remote Sessions (SSH)
 
 Codeman can run a session's agent on a **remote host over SSH** instead of the
-local machine. The agent (Claude, OpenCode, Codex, Gemini, or a plain shell)
+local machine. The agent (Claude, OpenCode, Codex, Antigravity, Gemini, Pi, Grok, or a plain shell)
 runs inside a `tmux` server **on the remote host**, so it survives the SSH
 connection dropping; Codeman attaches to it the same way it attaches to a local
 managed session.
@@ -30,7 +30,7 @@ Types live in `src/types/session.ts`; persistence in `src/remote-hosts.ts`.
 | `RemoteHost` (extends `RemoteSshOptions`) | A saved host: `id`, `label`, `host`, `username`, `port?`, `commands?` (per-mode launch command override). |
 | `RemoteCase` | A working directory on a host: `name`, `type: 'remote'`, `hostId`, `remotePath`. |
 | `SessionRemote` (extends `RemoteSshOptions`) | The resolved bundle stamped onto a live session: host coordinates + `remotePath` + `commands`, plus **`owned?`** and **`remoteSessionName?`** (COD-105 — see [Ownership](#ownership-launched-vs-discovered-and-attached-cod-105)). Built by `toSessionRemote(host, case)` (sets `owned: true`) for the launch path, or `toAttachedSessionRemote(host, name, path)` (sets `owned: false`) for the attach path. Both copy the advanced SSH options through so every connection is identical. |
-| `RemoteCommandMode` | `Extract<SessionMode, 'shell' \| 'claude' \| 'opencode' \| 'codex' \| 'gemini'>` — the modes that can run remotely. |
+| `RemoteCommandMode` | `Extract<SessionMode, 'shell' \| 'claude' \| 'opencode' \| 'codex' \| 'gemini' \| 'antigravity' \| 'pi' \| 'grok' \| 'deepseek' \| 'omp'>` — the modes that can run remotely. |
 | `RemoteSessionInfo` (COD-105) | One discovered remote tmux session: `name` (always `codeman-*`), `attached` (a client is connected), `created` (epoch s), `windows`. Returned by `listRemoteCodemanSessions()`. |
 
 Persistence is two flat JSON arrays in the instance data dir:
@@ -115,7 +115,12 @@ Key points:
 - **`exec <cli>`** replaces the pane shell with the agent, so the pane PID *is*
   the agent. The per-mode command comes from `remote.commands?.[mode]` or
   `defaultRemoteCommandForMode(mode)` (`exec claude` / `exec opencode` /
-  `exec codex` / `exec gemini` / `exec bash -l`).
+  `exec codex` / `exec gemini` / `exec agy` / `exec bash -l`).
+  ⚠️ **claude and omp no longer take that path**: both have their own arm in
+  `buildRemoteLaunchCommand` so a respawn can continue the same conversation
+  (see [Respawn / reattach continuation](#respawn--reattach-continuation)), and
+  because the claude arm is an `a || b` pair under `-c`, its pane PID is the
+  **login shell**, not the agent.
 - The **whole tmux invocation is a single shell-quoted ssh argument**, and the
   pane command is independently quoted, so a `remotePath` with spaces is safe.
 - Connection options come from the **same `buildSshConnectionArgs(remote)`** as
@@ -202,6 +207,322 @@ The early return is a structural guarantee that **no code path can ever issue a
 remote `kill-session` for a session we don't own** — the only `kill-session` run is
 on the local socket, which never reaches the remote socket.
 
+## Respawn / reattach continuation
+
+A dropped connection or a dead pane must reconnect to the **same conversation**,
+not launch a fresh one — the whole point of a durable remote session.
+
+- **Claude**: the launch command is idempotent — `claude --session-id <id> ||
+claude --resume <id>` (see `buildRemoteLaunchCommand`'s claude branch). The
+  first run creates the conversation under the deterministic session id; every
+  later reattach/respawn re-runs the same line, `--session-id` fails
+  ("already in use"), and the `||` fallback resumes it.
+- **OMP**: `omp` has no equivalent idempotent single-line form, so
+  `Session._pinOmpRespawnId()` resolves and pins an explicit `--resume <id>`
+  before a respawn (mirroring the local/docker builders, rendered through the
+  same `buildSpawnCommandFromRegistry` engine — not a hand-rolled command and
+  not `appendResumeFlag()`, which is docker-only and cannot work here: appending
+  a flag after the quoted `-c 'omp'` hands the id to the login shell as `$0`
+  instead of to `omp`). ⚠️ **The resolver only ever reads THIS host's local
+  `~/.omp/agent/sessions/`**, which is meaningless for a remote session — the
+  conversation and its session file live on the remote host, under the remote
+  user's home. For a remote session, `_pinOmpRespawnId()` therefore skips local
+  resolution entirely and falls back to `omp`'s own ambiguous `--continue`
+  (`ompConfig.continueSession`), which the remote pane command already renders.
+  This is a known, accepted degradation versus the local/docker paths' exact
+  `--resume` pin — safe in practice because each remote respawn talks to
+  exactly one remote pane's own omp history, so "most recent" is normally
+  correct, but it can drift the same way `--continue` always could if two
+  remote sessions ever share one remote directory.
+
+## Auto-reconnect vs. a clean agent exit
+
+`remoteAutoReconnect` (default ON) watches for a dropped SSH connection and
+reconnects with bounded backoff. It must **never** revive a session whose agent
+exited cleanly (Ctrl-C, Ctrl-D, `exit`) — that tears down the durable remote
+tmux session itself, and a transport-level `isPaneDead()` cannot tell that apart
+from a plain network drop. `remoteTmuxSessionAlive()` (#355) resolves this by
+probing the remote host directly: `tmux -L codeman-remote has-session -t
+codeman-ssh-<id8>` over the same `buildSshConnectionArgs` as launch, classified
+by **exit status alone** (`classifyRemoteAliveExit`: `0` = alive, ssh's `255` or
+a timeout = unknown, anything else = gone) — `has-session` prints nothing on
+success, so reading stdout would misclassify every live session as gone. An
+unreachable host answers "unknown", which also means do not revive. The answer
+is cached per session and cleared whenever the pane is next seen alive, so a
+stale `true` from one transport drop can never revive the NEXT clean exit.
+
+## File access over SSH
+
+A remote case's `workingDir` is an absolute path on the **remote** host
+(`Session.workingDir = RemoteCase.remotePath`), so the file routes cannot use local
+`fs`: a local `realpathSync` on a remote-only path fails by construction, which is why
+previewing a file used to answer `404 File not found` for a case that was working
+perfectly (#415). `src/remote-files.ts` is the one module that reads remote bytes,
+and it follows the same rule as the launch path: every ssh command line comes from
+`buildSshConnectionArgs()` — **never** a hand-built ssh line.
+
+| Request | What happens |
+|---------|--------------|
+| `GET /api/sessions/:id/file-raw` | Streamed over `ssh` (`cat`, or `tail -c +N \| head -c L` for a `Range`); the same 200/206/416 contract as a local file, so `<video>`/`<audio>` seeking works |
+| `GET /api/sessions/:id/file-content` | `cat` into memory, capped by the existing text limit; `edit=1` answers `400` (see below) and `editable` is always `false` |
+| `PUT /api/sessions/:id/file-content` | `400` before any path is looked at: the guard sits AHEAD of the local path validation, because with a same-named directory on the Codeman host (an `sshfs` mount) the write would otherwise land on the local twin |
+| `GET /api/sessions/:id/file-preview` | Non-office files redirect to `file-raw` (which works remotely); docx/pptx answer `400` |
+| `GET /api/sessions/:id/file-thumbnail` | `400` for remote files |
+| `POST /api/sessions/:id/attachments` | Registers an absolute path that lives on the **remote** host (a clicked link pointing outside the case directory) by probing it there |
+| `GET /api/sessions/:id/attachments/:attachmentId/raw` | Streams the registered remote file over ssh, same 200/206/416 contract; `preview` (office) and `thumbnail` answer `400` |
+| `GET /api/sessions/:id/attachments/:attachmentId`, `GET …/attachments` (history) | Size/mtime/existence resolved over ssh, so a remote entry is not reported `missing`; the history list resolves EVERY entry in one batched probe, never one connection per entry |
+
+⚠️ The attachment route is the one a clicked path takes when it is **outside** the case
+directory (a remote `/tmp` scratchpad capture, a screenshot elsewhere in the home dir):
+the frontend's `_isExternalPreviewPath()` sends every absolute path that is not under
+`workingDir` there, so fixing only `file-raw` would leave exactly that half broken.
+
+Guard order is deliberately **the same as locally**, and the checks are not weakened
+by the transport:
+
+1. Ownership (`findSessionOrFail` / the scope helper) — unchanged.
+2. Lexical containment of `workingDir + path` — a `../` escape is refused before any
+   connection is opened.
+3. ONE ssh round trip that returns `realpath` **and** `stat` for the path **and** the
+   workspace root (`remoteProbePaths`). Resolving the root remotely is what keeps the
+   boundary honest for a symlinked `remotePath`. The probe uses `readlink -f` when
+   available; on a host without it (macOS before 12.3) a POSIX fallback canonicalizes
+   the directory chain with `cd -P`/`pwd -P` and then follows the LAST component with
+   plain `readlink` for a bounded number of hops. ⚠️ **The fallback fails closed**: a
+   path it cannot fully resolve (a loop, a `readlink` failure, the hop cap) is reported
+   as unresolvable and answers 404, never as its own unresolved string. An earlier
+   version resolved only the directory chain, so `ws/notes.txt -> ~/.ssh/id_rsa` passed
+   containment under the link's own path while `cat` followed it to the key.
+   Records come back NUL-separated and index-keyed (`<index>|kind|size|mtime|realPath`,
+   after a leading NUL that fences off any login banner), so a filename containing a
+   newline cannot shift the alignment.
+4. Containment of the remote realpath against the remote root. The sensitive-path
+   blocklist then applies on whichever routes already apply it locally (`/api/download`,
+   attachment registration, edit mode — where resolving symlinks first is what makes it
+   meaningful); the remote branch neither drops a guard the local path has nor invents a
+   stricter one. One entry of that blocklist is host-bound by construction: the three
+   home-anchored members (`~/.claude.json`, `~/.claude/settings.json`,
+   `~/.claude/settings.local.json`) are compared against the **Codeman host's** home
+   directory, so they do not match a remote home at a different path. Everything else in
+   the list is depth-anchored (`/.ssh/`, `/.aws/credentials`, `/.claude/.credentials.json`,
+   `/etc/shadow`, ...) and applies to a remote path unchanged.
+5. Size cap (`CODEMAN_MAX_DOWNLOAD_BYTES`) applied to the **remote** size, before the
+   body is requested.
+
+The path arrives from the browser (`?path=`) and is interpolated as a single
+`shellescape`-quoted token, in a command that is itself shellescaped into the ssh
+line; `BatchMode=yes` means a host needing a passphrase fails fast instead of hanging.
+A failed connection is reported as **502** with the remote reason — never a 404, which
+used to make an unreachable host look like a typo in the agent's output. The reason is
+the first stderr line, the timeout, or the exit code; never Node's `Command failed: …`
+message, which would carry the identity-file path and the probe script into the body.
+
+**Connections are bounded.** Every probe and buffered read runs through a small global
+semaphore (`src/remote-ssh-limiter.ts`, default 4, `CODEMAN_MAX_REMOTE_FILE_SSH`), the
+attachment-history list resolves its whole history in one batched probe instead of one
+handshake per entry, and probes are chunked at 40 paths per round trip. Terminal output
+in a remote session is written on the remote host, so a prompt-injected agent printing
+hundreds of `codeman://attach` links used to make the server fork one `ssh` per link,
+each holding a 20 s probe timeout, and a 100-entry history re-listed on every
+`attachment:detected` event tripped OpenSSH's default `MaxStartups 10:30:100`. Streams
+(`file-raw`, by-id `raw`) are not counted: one is held per browser request for the life
+of a playback, and each is gated behind a counted probe anyway.
+
+⚠️ **There is deliberately NO local fallback.** A remote case reads the remote bytes or
+fails, even when a file with the same absolute name exists on the Codeman host — which
+is the ordinary case for the documented stop-gap workaround, an `sshfs` mount of the
+remote tree at the identical path. Serving the local twin instead would silently hand
+back a DIFFERENT filesystem's bytes under a name the user believes is the remote file
+(a stale mount, a different checkout, a leftover file), and the failure would be
+invisible. An existing mount therefore stops being load-bearing for previews and
+downloads but is harmless, and a missing remote file stays a 404 even if the mount
+still has it.
+
+**Not available over ssh (by choice, not by accident):** editing a file (writes would
+need SFTP; `docs/file-viewer-edit-plan.md` §6), office-document previews and
+generated thumbnails (both need the bytes on the server's disk — no remote file is ever
+spilled onto the server), the file-tree/picker listings, and `tail-file`. Those routes
+are still local-only, so with an `sshfs` mount in place they read the mounted copy —
+the two views can only disagree when that mount is stale. Docker cases are unaffected:
+their workspace is bind-mounted at the same absolute path, so local `fs` reads real bytes.
+
+⚠️ A remote record stores the **remote** path, and the same absolute path STRING means a
+different file on each host. What decides which host to read is therefore never the
+path but the SESSION (`session.remote`): a remote session never falls back to local
+`fs`, and a local session never opens an ssh connection — including for attachment
+records, which are keyed to the session that registered them.
+
+## Wake-on-LAN from user input
+
+A durable remote session survives an SSH drop (COD-104/108), but nothing brought the
+HOST back. When the remote machine suspended, the local pane's `ssh` child **stalled**
+rather than exited: `tmux send-keys` SUCCEEDS against a stalled pane, so typed input
+vanished with no error anywhere, and without a keepalive the pane could look alive for
+the OS TCP timeout. The only recovery was waiting for the reconnect watcher, which
+gave up after ~13 minutes and, once exhausted, never retried.
+
+An **optional** `wakeMac` (one or more MAC addresses, comma-separated) or `wakeCommand` on a
+remote host closes that: on user input, `POST /api/sessions/:id/input` probes the host, and if
+it is unreachable it wakes it, polls until the host answers, reattaches the pane
+(`Session.reattachRemote()`, which idempotently attaches the still-running remote tmux — the
+agent conversation is not restarted), and flushes the input that arrived meanwhile.
+Implementation: `src/remote-wake.ts`.
+
+The same wake path also serves **opening** a session, which is where a sleeping host used to
+be a dead end: pressing Run on a remote case (`POST /api/quick-start`) or Attach on a
+discovered remote tmux session (`POST /api/sessions` + `attachRemoteSession`) probes the host
+first, and on a sleeping one wakes it, waits for SSH and only then runs the tmux prereq probe.
+Without that the run failed with `could not verify tmux on remote host …` — an ssh error that
+blames tmux for a machine that is merely suspended. The wait is **blocking** (the caller gets
+the session or the error) but bounded by `REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS` (40 s) rather
+than the 90 s session default, because the dashboard sits behind a reverse proxy whose default
+`proxy_read_timeout` is 60 s: a longer wait would be cut off at the proxy while the session was
+still being created. The budget covers the whole request, not just the wait (40 s wake + 1.5 s
+probe + the tmux prereq probe's own 15 s timeout = 56.5 s worst case). A host with no wake target is not even probed on this path, so nothing
+changes for it, and `remote:hostWaking` is broadcast without a `sessionId` (the toast then reads
+"the session starts when it is back" — there is no session yet, and no input queued behind it).
+
+Two wake paths, `wakeCommand` first because it is the explicit override:
+
+- **`wakeMac`** — Codeman builds the magic packet itself (`buildMagicPacket`, six `0xFF`
+  bytes then the MAC repeated 16×; the shape is asserted byte-for-byte) and broadcasts it
+  over UDP port 9 (`sendWakePackets`). This is the normal case: no external script, and one
+  MAC list per host instead of one per consumer.
+- **`wakeCommand`** — a single executable path, run WITHOUT a shell. For hosts that need a
+  router/another machine to send the packet.
+
+**UI**: a banner (`#hostWakeBanner`, `host-wake-ui.js`) appears while the ACTIVE remote
+session's host is unreachable — amber, since the Codeman session is healthy and only the
+machine is asleep. With a wake target the action is **Wake** (`POST /api/sessions/:id/wake`);
+with none it is **Configure WoL** and opens `#wakeConfigModal`, a small form for that host's
+`wakeMac`/`wakeCommand` that saves with `PUT /api/remote-hosts/:id` (in multi-user mode that
+GET is admin-only, so a non-admin is told the setting is admin-only instead of "host not
+found"). Reachability for the banner comes from `GET /api/sessions/:id/reachability`: once
+when the remote tab is activated (a user action), and every 30 s while the tab is visible
+**only for a host with a wake target** — each poll is a TCP connect to the host, and a timer
+that connects to a host Codeman could not wake anyway is exactly the timer-driven traffic
+the keepalive rule below rejects (it cannot wake a host, but it can keep an activity-based
+suspend timer from firing). A host the probe cannot reach (see the next section) is never
+polled. ⚠️ The button is pressed from the SAME
+dashboard as Run/Attach, so it holds its request open under the same proxy and uses the same
+40 s budget — and it **queues nothing**: browser keystrokes travel over the WebSocket, which
+deliberately does not pass through the registry (that is the hot path this feature keeps its
+hands off), so the banner says "waiting for the host to come back" for the button and only
+claims "input is queued" when the HTTP input path actually buffered bytes
+(`queuedInput` on the two SSE events).
+
+**Hosts behind a jump host or SOCKS proxy are reachability-UNKNOWN.** The probe is a bare
+TCP connect to `host:port`, and a host reached through `jumpHost`, `socksProxy` or a
+`ProxyCommand`/`ProxyJump` in `extraSshOptions` does not answer that even while ssh works —
+the direct address may not route at all (the cloudflared case). Acting on the resulting
+"unreachable" verdict was wrong three times over: a permanent banner over a healthy session,
+a create-path error that replaced a genuine "needs tmux" with "not reachable", and — with a
+wake target configured — every HTTP input buffered for the life of the session, because the
+readiness poll could never succeed. `isProbeable()` (`remote-wake.ts`) decides from the
+proxy fields, which travel on `WakeableRemote`; for such a host the registry delivers input
+unchanged, `GET …/reachability` answers `reachable: null, probeable: false` (unknown is not
+`false`, and only a proven `false` raises the banner), the create/attach path is not gated
+(`ensureHostAwake` → `'unprobeable'`, handled like `'no-target'`), and the quick-start
+"not reachable" message is reserved for a **proven** unreachable host (`=== false`). A wake
+target can still be fired for it through `POST /api/sessions/:id/wake`, blind: the packet or
+command goes out and the response says only whether it did — no readiness poll, no reattach
+(the COD-108 watcher owns the pane once ssh works again), no "waking" toast.
+
+The invariants worth keeping:
+
+- **Authorization comes before the wake.** In multi-user mode the attach path
+  (`POST /api/sessions` + `attachRemoteSession`) answers `403` to a non-admin BEFORE the
+  host is looked up or probed: remote hosts are admin-only infrastructure everywhere else
+  (the list is `[]` for a non-admin, write and discovery routes are `adminOnly`), and the
+  wake spawns the host's `wakeCommand` or broadcasts a packet — a gate that came after the
+  wake handed an unprivileged account a way to run that executable for any configured
+  `hostId`, hold the request for the wake budget, and only then be refused for the
+  workingDir. The quick-start path resolves its remote case through `canAccessOwned`
+  first. Pinned in `test/routes/session-remote-wake.test.ts` (wake spy stays empty).
+- **The caller is told what happened to its bytes.** The non-wait input route answers
+  `{buffered:true}` when the registry took the chunk and `{buffered:true, dropped:true}`
+  when it was over the cap and is gone; the send-and-wait route answers `OPERATION_FAILED`
+  when the host never comes back, like the create and attach paths, instead of writing
+  into the stalled pane and reporting `delivered:true` plus a timeout. Flushed chunks are
+  written with `fromUser`, so a first prompt that was buffered through a wake can still
+  name the tab.
+- **Only an EXPLICIT request may wake a host:** user input on an established session, the wake
+  button, or the user's own session create/attach request (`ensureHostAwake`). Everything that
+  runs on a TIMER must never wake one — the COD-108 watcher, the server's dropped-session
+  handler, boot recovery and session discovery have no access to the wake registry, and neither
+  has the shared session service, because `cron-service.ts` builds sessions there with nobody
+  waiting on the answer; a wake on such a path would re-wake the host seconds after every
+  suspend, so it could never stay asleep (the same failure `hufflepuff-mcp-lazy` exists to
+  prevent for MCP keepalives). A reachability check, a discovery listing and the tmux prereq
+  probe never wake: they are questions, not actions. All of it is enforced by tests in
+  `test/remote-wake.test.ts` (two wiring guards: one pins the importers — the route module and
+  `server.ts`, which holds the registry for its LIFETIME only, `drop()` on session cleanup and
+  `stop()` on shutdown — and one asserts `server.ts` calls nothing but those two, while
+  `ensureHostAwake` has exactly one caller file) and `test/routes/session-remote-wake.test.ts`,
+  not by comments.
+- **Detection is a bare TCP connect** to the SSH port (then the configured `port`, else 22),
+  throttled per session, and only for wake-enabled hosts. No `ServerAliveInterval` is added to
+  the launch command: keepalives push bytes into an otherwise idle connection every interval,
+  which is exactly what a byte-threshold idle detector must not count as activity. A probe is
+  ~200 bytes per 30 s, orders of magnitude below any such threshold, and the SYN alone cannot
+  wake a host.
+- **Input is buffered while a wake is in flight** (`REMOTE_WAKE_PENDING_MAX_BYTES`,
+  oldest whole chunks dropped, bounded so user input cannot grow memory) and flushed in
+  order after the reattach, with a settle delay so bytes cannot land in a still-connecting
+  pane. ⚠️ A chunk LARGER than the cap (one big paste is one `input` value) is dropped
+  **outright**, never trimmed: it was never typed character by character, so its tail is not
+  "what the user just typed" but a fragment of a command they never sent — the drop is logged
+  instead. ⚠️ Only the HTTP input route reaches the registry; the **WebSocket keystroke path
+  is deliberately NOT wake-aware**, so typing into a sleeping host sends nothing and queues
+  nothing (the banner's Wake button is the recovery for that case, which is why it must not
+  promise queued input). The **send-and-wait** path blocks on the wake instead — its response
+  is open anyway, and buffering would break the wait contract. ⚠️ A flush write that FAILS
+  drops the whole remaining buffer (logged) rather than retaining it: the wake still resolves
+  and marks the host reachable, so the next input takes the deliver path while a retained
+  chunk would wait for the NEXT wake — replayed hours later, after everything typed since,
+  possibly ending in a carriage return. Same policy as the oversized paste.
+- **The command runs without a shell** (`spawn(path, [], { stdio: 'ignore' })` — `shell`
+  defaults to `false`), the schema
+  requires a single executable path (no arguments, no `$`/backtick), and `wakeMac` is a
+  structural hex-pair allowlist. A broken or missing wake target fails the wake, never the
+  input route.
+- **`wakeMac`/`wakeCommand` are host-level config, refreshed on recovery AND live**
+  (`rehydrateRemoteHostFields` in `src/remote-hosts.ts` plus `RemoteWakeDeps.resolveRemote`).
+  A session's `remote` block is persisted at launch time, so a field added to
+  `remote-hosts.json` later would otherwise never reach an already-running session — not even
+  across a Codeman restart, and certainly not right after saving the banner's config dialog.
+  Recovery rehydration covers restarts, the (throttled, cache-backed) resolver covers the live
+  session; the host config is authoritative for both (removing the field disables the feature
+  again). Other host-level fields deliberately stay as persisted, so neither path can
+  silently re-point an existing pane's SSH options.
+- **UI/SSE**: `remote:hostWaking` and `remote:hostWakeFailed` (plus the reused
+  `remote:sessionReconnected`) drive the banner and toasts, all from `host-wake-ui.js` —
+  its handlers are the ONLY definitions, since a second one in another mixin would be
+  silently shadowed by script order. Both carry `queuedInput`, which is true only when the
+  server actually holds bytes for that session — the wording keys off that, not off "a wake
+  is running", so the button path never claims input is queued. In multi-user mode the
+  whole `remote:` family is **session-scoped** (`deriveSseHint`, `server.ts`): an event with
+  a `sessionId` reaches that session's owner, and the create/attach wake — which has no
+  session yet — carries the requesting `username` instead (`ensureHostAwake({ requestedBy })`),
+  since its payload names a `hostId`/`label` that `GET /api/remote-hosts` withholds from
+  non-admins. With neither, it reaches admins only.
+- **No real IO under vitest.** `probeRemoteHostReachable`, `runRemoteWakeCommand` and the
+  default UDP socket of `sendWakePackets` throw under `VITEST` (as `remote-files.ts` does),
+  so a test that reaches the defaults fails loudly instead of connecting, spawning or
+  broadcasting from CI. Every consumer injects its IO (`RemoteWakeDeps`, the socket
+  factory); `createDefaultRemoteWakeDeps({ probe })` also polls readiness with THAT probe,
+  which is the leak the guard found.
+
+Tests: `test/remote-wake.test.ts` (decision/throttle table, single-flight registry,
+buffering + flush order, MAC parsing/magic packet, live host-config resolution, the proxied
+host, SSE payload routing, the vitest IO guard, and the wiring guard),
+`test/routes/session-remote-wake.test.ts` (the input route buffers instead of writing into a
+sleeping host — and writes straight into a proxied one —, the reachability route never wakes
+and reports a proxied host as unknown, and the wake route reports the no-target case the UI
+turns into "configure WoL"), `test/sse-routing-remote.test.ts` (multi-user routing of the
+`remote:` family) and `test/host-wake-banner.test.ts` (banner visibility and when the poller
+may connect).
+
 ## API
 
 Routes are registered in `src/web/routes/case-routes.ts`:
@@ -215,6 +536,10 @@ Routes are registered in `src/web/routes/case-routes.ts`:
 | `GET` | `/api/remote-hosts/:hostId/sessions` | Discover `codeman-*` sessions on the host (COD-105; `listRemoteCodemanSessions`, never errors) |
 | `POST` | `/api/cases/remote-link` | Link a case to a remote host (creates the `RemoteCase`) |
 
+`RemoteHost` accepts the optional `wakeMac` (magic packet, sent by Codeman) and `wakeCommand`
+(single executable path, run without a shell, takes precedence) — see **Wake-on-LAN from user
+input** above.
+
 Attaching to a discovered session is a **session-create** path, not a host route:
 `POST /api/sessions` accepts `attachRemoteSession: { hostId, remoteSessionName }`
 (schema in `schemas.ts`; `remoteSessionName` must match `^codeman-[a-zA-Z0-9._-]+$`),

docs/scrollback-fix-plan.md

@@ -0,0 +1,301 @@
+# Scrollback fix plan (issue #205)
+
+Status: IMPLEMENTED on `fix/scrollback-shell-alt-screen` (2026-08-07), with one deliberate
+divergence from the recommendation below. Kept for the diagnosis record; the measured evidence
+behind it is `docs/scrollback-issues-analysis.md`, and the mechanisms as shipped are documented
+in `docs/architecture-invariants.md` (§ Full-scrollback replay, § Terminal scrollback: strip
+flavors and wheel/touch forwarding).
+
+What shipped vs. what this doc proposed:
+
+- **Bug A (deltaMode)**: implemented as specified (`_wheelScrollLines()` normalizes
+  line/page/pixel units, Shift-axis trap kept).
+- **Bug B (shell scrollback)**: implemented via the NARROW alt-screen strip for tmux-backed
+  shell/opencode/antigravity plus the scroll-to-top `full=1` re-pull, NOT the recommended
+  approach (a) `tmux mouse on`. The measurements in the analysis doc showed the alt buffer
+  comes from tmux's own client-side `smcup` at attach (tmux never forwards a pane program's
+  alt-screen toggles), so stripping that one sequence fixes both symptoms with no selection
+  tradeoff, keeps vim/less/htop untouched, and the re-pull also covers the repaint-burst
+  history loss that `mouse on` would not have addressed.
+- **Invariant change**: the "viewport-at-bottom gate stays" invariant below was deliberately
+  DROPPED for forwarding modes: a repaint-mode CLI keeps no real terminal scrollback, so the
+  gate pinned users to a buffer of stale frames whenever the viewport parked off-bottom.
+  Forwarding now snaps to bottom first; Shift+wheel and the opt-out setting keep local
+  scrollback reachable. Touch forwards through the same gate (the mobile half of the fix).
+- **Finding 5 (remote probe)**: implemented (`probeRemoteCliVersion` over ssh, deferred at
+  session start, same login-shell wrapper as the launch).
+
+## RETEST FAILED (2026-08-07, after v1.12.0 shipped) — analysis round 2
+
+mtiller retested on 1.12.0 and reports it is NOT fixed (issue #205 comment, 2026-08-07 12:12 UTC;
+issue reopened same day with clarifying questions: mouse vs trackpad, Shift+scroll behavior,
+Claude vs shell session on the phone, and an iOS full-tab-kill to rule out stale JS). Two
+failure signatures, now analyzed against the SHIPPED 1.12.0 code (not the pre-fix code):
+
+1. **iPhone Safari (Claude session assumed)**: touch scrollback goes back only a limited
+   amount and sometimes REPEATS blocks of text; unreliable.
+2. **Firefox on macOS (mouse)**: wheel does NOTHING at all, while Fn+Up (= PageUp) pages back
+   through INTACT text.
+
+### Ruled out by code reading
+
+- deltaMode mishandling: `_wheelScrollLinesFloat` normalizes line/page/pixel units correctly;
+  a Firefox line-mode notch yields ±3 lines. Not the bug.
+- Ephemeral transport: `_sendInputEphemeral` (app.js) has a POST fallback when WS is down.
+- Service worker: sw.js is network-first with cache fallback; it serves stale JS only when the
+  fetch FAILS (flaky mobile connection can do this — relevant to "unreliable" on the phone,
+  and the fixed `CACHE_NAME = 'codeman-v1'` never invalidates that offline copy).
+
+### The load-bearing observation: PageUp works, the wheel does not
+
+Fn+Up is a KEYBOARD event: xterm encodes PageUp and Claude pages its own transcript (intact
+text proves Claude-side history is fine and the PTY input path is fine). The wheel path is the
+capture-phase handler, and for a Claude session it has exactly two branches:
+
+- **Forwarding branch** (`_shouldForwardWheelToApp` true): snap-to-bottom + SGR reports. If
+  this branch ran, the user would see the same paging motion Fn+Up produces. They see nothing.
+- **Local branch** (gate false): `_smoothScrollBy` over xterm's local buffer. For a Claude
+  pane in repaint mode, tmux keeps `history_size≈0`, so `?full=1` returns roughly one frame:
+  the local buffer is structurally HOLLOW, the top-of-buffer re-pull recovers nothing, and the
+  wheel looks completely dead. **This matches every observed detail on Firefox.**
+
+So the working hypothesis is that mtiller's sessions evaluate the gate FALSE. The gate
+(`_shouldForwardWheelToApp`) has exactly four false-paths worth checking, in likelihood order:
+
+1. **`terminalWheelLocalScrollback` opt-out is ON.** Plausible: a user whose scrolling was
+   broken on 1.11.x may well have toggled "Wheel scrolls local history" while trying to fix
+   it. On 1.12.0 that setting now routes the wheel to a hollow local buffer = dead wheel on
+   desktop AND the stale-repaint-frames experience on the phone (see below). Ask, or check
+   what the setting does on their export.
+2. **`cliVersion` missing — CONFIRMED BUG, independent of whether it is mtiller's**:
+   `getClaudeCliVersion()` (utils/claude-cli-resolver.ts:124-148) caches its result
+   process-wide including FAILURE: on any exception it sets `_claudeVersion = null`, and the
+   guard is `!== undefined`, so a single failed/timed-out probe (5s `EXEC_TIMEOUT_MS`; PATH
+   under systemd/launchd; transient fs hiccup) at the FIRST Claude session start disables
+   wheel forwarding for every Claude session until the server restarts. Fix: cache success
+   permanently, but let failure retry (retry on next call, or a short negative-cache TTL).
+   Note that mtiller sees identical breakage on phone + iPad + laptop, which points at a
+   SERVER-side/session-side cause exactly like this (cliVersion is shared by all devices)
+   rather than anything browser-specific.
+3. **Claude Code genuinely < 2.1.187** on their machine: gate false BY DESIGN, but the
+   resulting UX is a dead-end (no local history to fall back on).
+4. mouseTrackingMode non-none (a DECSET leaked past the strip, e.g. emitted before attach or
+   split across chunks in a way the carry missed): would also kill the container handler via
+   the early return. Least likely, checkable via `terminal.modes.mouseTrackingMode` in console.
+
+### The iPhone symptoms fit the same gate-false story
+
+Touch with gate false = local `scrollLines()` over whatever repaint frames accumulated:
+"repeats blocks of text" is literally what a buffer of successive overlapping repaint frames
+looks like; "limited amount" is its thinness; "unreliable" is burst-dependence (finding 2)
+PLUS the new re-pull being actively DESTRUCTIVE for repaint panes: `_maybeRefetchFullHistory`
+does `_resetTerminalForReplay()` then writes the fetched capture, and when that capture is
+one frame (Claude pane, `history_size≈0`) it REPLACES a multi-frame buffer with less than the
+user had, mid-scroll. Stale pre-1.12 JS on the phone (suspended Safari tab) remains possible
+until they confirm the tab kill.
+
+### Fix directions, ranked
+
+1. **Make the re-pull refuse downgrades** (`_maybeRefetchFullHistory`, app.js): if the fetched
+   capture would yield FEWER buffer rows than currently present, skip the reset+rewrite and
+   keep the richer buffer (optionally cache-mark the session "re-pull useless"). Small, safe,
+   kills the "got worse after scrolling to top" class. Consider skipping the re-pull entirely
+   for forwarding-capable modes where tmux keeps no history.
+2. **Rescue the gate-false Claude dead-end with PageUp forwarding**: when mode is `claude`,
+   the gate is false, AND the local buffer has no scrollback (`baseY === 0`), translate wheel
+   lines into coalesced PageUp/PageDown key sends (mtiller just proved Claude pages correctly
+   on PageUp even on their version). Zero regression risk under that triple guard: sessions
+   with real local history keep local scrolling; only the currently-dead path changes.
+   Caveat: older Claude menus may react to PageUp; acceptable against "completely dead".
+3. **Audit `getClaudeCliVersion()` failure caching** (utils/claude-cli-resolver.ts): a cached
+   empty probe must retry (with backoff), not poison the process.
+4. **Guard the opt-out setting's footgun**: if `terminalWheelLocalScrollback` is ON for a
+   repaint-mode CLI session, local history is hollow; either scope the setting's effect to
+   modes with real local scrollback, or pair it with fix 2's PageUp fallback so it still
+   scrolls SOMETHING.
+5. **Add a one-line gate diagnostic**: log (once per session, console) WHY the wheel chose
+   local vs forward: `{mode, cliVersion, optOut, trackingMode}`. The #205 thread is now two
+   rounds deep on guesswork a single console line would have answered.
+
+### What shipped for round 2 (branch `fix/scrollback-205-round2`)
+
+All five directions above, implemented as ranked:
+
+1. **Downgrade guard** — `_replayWouldShrinkBuffer()` (terminal-ui.js) estimates the rows a
+   capture will occupy (ANSI stripped, `capture-pane -J` re-wrapping accounted for) and
+   `_maybeRefetchFullHistory` (app.js) skips the reset+rewrite when that is more than one
+   screen short of what xterm already holds. A refused session goes on
+   `_fullHistoryRepullUseless`, which raises its re-pull cooldown from 4s to 60s so a hollow
+   pane stops re-fetching. Measured A/B on a live Claude pane, same gesture, same buffer:
+   guard off → 341 rows collapse to 42 and every seeded row is gone; guard on → 341 rows
+   preserved. The tab-switch recovery it must not break still runs (shell buffer 401 → 44 on
+   a tab switch → 401 again after scrolling to the top).
+2. **PageUp/PageDown fallback** — `_maybePageCliTranscript()` translates wheel/touch travel
+   into coalesced `\x1b[5~` / `\x1b[6~` under the triple guard (claude mode, forwarding gate
+   false, `baseY === 0`), through the same 40ms queue as the SGR reports. Half a screen of
+   travel per page: the page key always jumps a whole screen, and a 1:1 mapping was
+   unusably slow with a discrete wheel. Shift is excluded — it keeps meaning "local
+   scrollback". Verified live: opt-out ON on a Claude session sends real PageUp/PageDown to
+   the PTY where the wheel previously did nothing.
+3. **Probe caching** — `getClaudeCliVersion()` no longer caches failure. Success is kept for
+   the process lifetime; a failed probe retries with a 1/2/4…15min backoff. The cache policy
+   is a pure function (`resolveClaudeCliVersion`) so the retry semantics are unit-testable
+   without spawning `claude`. The VITEST short-circuit now records nothing, where before it
+   wrote a permanent null.
+4. **Opt-out footgun** — handled by pairing rather than by scoping: the setting keeps meaning
+   exactly what it says (the wheel goes local), and fix 2 catches the case where "local" is
+   empty. Scoping the setting away from repaint-mode CLIs would have silently overridden an
+   explicit user choice. The App Settings tooltip now says to leave it off for Claude/Codex.
+5. **Diagnostic** — `_logScrollRouting()` prints one line per session per distinct decision:
+   `[scroll] <id> → forward-sgr|page-keys|local-scrollback|repull-refused-downgrade (mode=…,
+   cliVersion=…, localScrollbackOptOut=…, mouseTracking=…, localScrollbackRows=…)`. That
+   single line answers every open question in the list below.
+
+Still unanswered by code alone: whether mtiller's Claude Code is genuinely older than
+2.1.187 (false-path 3), and whether the iPhone was running stale JS. The diagnostic makes
+both self-reporting, so the retest ask is now "open the console and paste the `[scroll]` line".
+
+### What to get from mtiller (some already asked)
+
+- Shift+scroll behavior on Firefox (distinguishes hollow-local from handler-not-firing).
+- `claude --version` on the Mac (decides false-paths 2 vs 3).
+- App Settings → Input → "Wheel scrolls local history" state (false-path 1).
+- iPhone: Claude or shell session, and whether a full tab kill changes anything.
+- Browser console: `app.terminalUi?.terminal?.modes?.mouseTrackingMode` (false-path 4).
+
+## ROUND 3 (2026-08-09): Codex wheel dead — CONFIRMED AND FIXED
+
+DodgyBadger (Codex latest, Chrome, Windows 11): mouse wheel does nothing in a CODEX session
+while working fine in shell and web tabs; DRAGGING THE SCROLLBAR WORKS, so xterm's local
+buffer demonstrably has content for their codex pane. Analysis against the shipped code:
+
+- `_shouldForwardWheelToApp` returns true UNCONDITIONALLY for `codex` (no version gate, unlike
+  claude's `>= 2.1.187`), so every plain wheel tick is sent as SGR reports to Codex.
+- The "verified to scroll its transcript on SGR wheel reports" claim for codex predates
+  current Codex builds; if Codex latest ignores SGR wheel, forwarding eats the gesture while
+  the healthy local scrollback (proven by the working scrollbar) sits unused.
+- The #227 PageUp fallback cannot rescue this: it is gated to `claude` mode AND `baseY === 0`,
+  and codex here has real local scrollback. The `[scroll]` diagnostic will still say
+  `forward-sgr (mode=codex, ...)`, confirming the branch, worth asking the reporter to paste.
+
+**CONFIRMED by the reporter's `[scroll]` line (2026-08-09, PR #227 comment)**:
+`forward-sgr (mode=codex, cliVersion=unknown, localScrollbackOptOut=false, mouseTracking=none,
+localScrollbackRows=967)`. Forwarding branch active, 967 rows of healthy local scrollback
+unused, Codex ignoring the SGR reports. Environment: Codex latest, Chrome, Windows 11.
+
+**Measured against codex-cli 0.147.0** (isolated `tmux -L codexwheel`, fake `CODEX_HOME/auth.json`,
+history built with 401ing prompts), which settles it without needing a version gate at all:
+
+| Probe                                          | Result                                          |
+| ---------------------------------------------- | ----------------------------------------------- |
+| `#{mouse_any_flag}` once the TUI is up         | `0`: codex never enables mouse tracking         |
+| `#{alternate_on}`                              | `0`: inline viewport, not an alt-screen pager   |
+| `#{history_size}` while prompting              | grows 3 → 32: the transcript goes to scrollback |
+| 6 × `\x1b[<64;10;10M` written to the pane      | pane capture byte-identical, nothing happens    |
+| control: literal `zz`                          | pane changes, so the probe can see changes      |
+| `\x1b[<0;12;5M` + release (the click-tap path) | no change either: taps are no-ops, not garbage  |
+
+Codex has no in-app pager to drive: its history lives in the terminal's own scrollback, which is
+exactly what forwarding was stealing the gesture from. A version gate would be the wrong fix (and
+`cliVersion=unknown` means there is no codex probe to gate on anyway).
+
+**Fix (shipped):** `_shouldForwardWheelToApp` now returns true for `claude >= 2.1.187` and nothing
+else. Codex falls to the normal local-scrollback path like shell/gemini/opencode, so wheel and touch
+scroll the same history the scrollbar drag was already scrolling. The claude-only PageUp fallback is
+untouched: codex never needs it, its local buffer is real. Taps stay hand-encoded for codex
+(`_sessionUsesServerMouseStrip`), measured harmless, so click-to-position is merely unavailable
+there rather than damaging. Lesson for the next mode added to the forward list: "it is a strip mode"
+proves nothing, write a real SGR report into a live pane and diff the capture first.
+
+Verified end-to-end in Chromium against a live codex session on an isolated instance
+(`CODEMAN_INSTANCE=codexwheel`, port 5055, `envOverrides.CODEX_HOME` pointing at the fake auth
+dir): trusted `page.mouse.wheel` up now logs
+`[scroll] … → local-scrollback (mode=codex, …, localScrollbackRows=43)`, moves the viewport
+39 → 4 (back to the Codex banner), and sends ZERO bytes to the PTY. Unit coverage:
+`test/terminal-touch-tap.test.ts` ("only claude forwards — codex and gemini keep the local wheel").
+
+Original plan follows.
+
+## Reports
+
+- **Issue #205** (https://github.com/Ark0N/Codeman/issues/205), OPEN:
+  - **jonocodes** (author, 2026-08-03): SHELL session. Host Mac M4, brew tmux. On Android, touch-scrolling the terminal does nothing. On desktop, the mouse wheel cycles shell command history (acts like Up/Down arrows) instead of scrolling the screen.
+  - **mtiller** (comment, 2026-08-06): "similar issue just with scrolling backward to see agent output. This is with Firefox on MacOS." (Claude session implied.)
+- **Reddit r/selfhosted** comment `p21x6ts` by mmtiller (= mtiller on GitHub): scrolling broken enough across phone/iPad/laptop that they fall back to Claude's own remote-control feature. Churn-risk user who otherwise loves the product; fixing this has promo value beyond the bug itself.
+
+## How scrolling works today (read this before touching anything)
+
+Three independent paths, all in `src/web/public/terminal-ui.js` unless noted:
+
+1. **Desktop wheel** (container `wheel` listener, ~line 421): ALWAYS `preventDefault()`s, then either
+   - forwards synthetic SGR wheel reports to the app (`_sendSyntheticSgrWheel`, coalesced every 40ms, fire-and-forget) when `_shouldForwardWheelToApp(ev)` (~line 2823) passes: no Shift held, opt-out setting `terminalWheelLocalScrollback` off, xterm `mouseTrackingMode === 'none'`, session mode is `claude` with `cliVersion >= 2.1.187` or `codex`, and viewport is at bottom;
+   - otherwise scrolls xterm's LOCAL scrollback via `terminal.scrollLines(lines)`.
+   - `lines` comes from `_wheelScrollLines(ev)` (~line 2818): `delta / 25`, i.e. it assumes PIXEL deltas.
+   - NOTE: xterm.js's own internal wheel handler sits on an element INSIDE the container, so it runs FIRST (bubble order) and is not suppressed by the container's `preventDefault`.
+2. **Touch** (touchstart/move/end, ~lines 441-585): converts touch deltas to `terminal.scrollLines()` with momentum. Touch is ALWAYS local-scrollback, never forwarded to the app. Tap-to-position (touchend, ~line 533) is separate and already handles both mouse-tracking-on and server-strip cases.
+3. **Server-side strip** (`_handleTerminalOutput`, `src/session.ts:1384`): for modes in `isAltScreenStripMode()` (`src/session.ts:179` = `codex | claude | gemini`), strips alt-screen switches (`?47/?1047/?1049`), scrollback erase (`3J`), and mouse-tracking DECSETs (`?1000-?1007` except `?1004` focus) so content stays in xterm's normal buffer with scrollback intact. Includes a chunk-boundary carry so split sequences can't leak. `shell` and `opencode` (and `antigravity`) are deliberately EXCLUDED: arbitrary shell programs (vim/less/htop) legitimately need the alt screen. There is a parity copy of this strip on the replay path (`src/web/routes/session-routes.ts`, ~line 1697) and a frontend parity check `_sessionUsesServerMouseStrip()` (terminal-ui.js ~line 2751). All three must stay in sync.
+4. Related: full-scrollback replay (`GET .../terminal?full=1` on first buffer load) fills xterm local scrollback; client scrollback is hardcoded 50k (`DEFAULT_SCROLLBACK`, constants.js) vs tmux 100k.
+
+## Diagnosis
+
+### Bug A: Firefox wheel deltas (mtiller's desktop case)
+
+`_wheelScrollLines()` divides by 25 assuming `WheelEvent.deltaY` is pixels (`deltaMode === 0`, Chrome/Safari behavior). Firefox commonly fires `deltaMode === 1` (LINE units, deltaY around 1-3 per notch), so `Math.round(3/25) = 0` and the `|| ±1` fallback yields 1 line per event. With a discrete mouse wheel that is 1 line per notch: scrolling feels dead/broken. This hits BOTH the local-scroll path and the forwarded path, since both use the same function.
+
+**Fix**: normalize by `ev.deltaMode` in `_wheelScrollLines()`:
+- `deltaMode 0` (pixels): current behavior, `delta / 25`.
+- `deltaMode 1` (lines): use the delta directly (round, keep sign fallback).
+- `deltaMode 2` (pages): `delta * terminal.rows` (or a sane page size).
+Keep the existing Shift-axis trap intact: on macOS trackpads Shift+two-finger scroll arrives as a HORIZONTAL wheel (deltaX carries the magnitude, deltaY ~0); that's why the function reads deltaX when Shift is held (issue #154). Don't lose it.
+
+**Verify**: don't trust this diagnosis blindly. First reproduce in real Firefox on macOS and log `deltaMode`/`deltaY` (Firefox trackpad input can arrive as pixels; external mouse as lines). Also confirm the session's `cliVersion` probe succeeded (a failed probe disables forwarding entirely, which would point elsewhere). Unit-test by dispatching synthetic `WheelEvent`s with explicit `deltaMode` values; a Playwright `firefox` project pass is the end-to-end check.
+
+### Bug B: shell mode has NO working scrollback at all (jonocodes)
+
+Chain: shell mode is excluded from the alt-screen strip (correctly) → tmux attaches on the alternate screen → xterm's alt buffer has zero scrollback. Consequences:
+- **Wheel**: xterm's own internal wheel handler runs first and, in the alt buffer, converts wheel ticks into Up/Down arrow keys (alternateScroll behavior). The shell receives arrows → command history cycles. That is jonocodes' exact desktop symptom. The container handler's `scrollLines()` afterwards is a no-op (no scrollback in alt buffer).
+- **Touch**: the touch handler's `scrollLines()` is equally a no-op → "scrolling does nothing" on Android. Exact symptom two.
+- The real history exists the whole time in tmux's 100k-line buffer; nothing exposes it.
+
+**Fix, recommended approach (a): enable tmux `mouse on` for shell sessions.**
+- Server-side, set `mouse on` scoped to shell sessions' tmux sessions (`tmux set-option -t <session> mouse on` at create + on attach of recovered sessions). Do NOT set it globally on the socket: claude/codex/gemini sessions rely on the DECSET strip and must not change.
+- What this buys, all natively: tmux enables mouse tracking on the outer terminal → xterm `mouseTrackingMode` goes non-none → the container handler stands down (line ~2830 check) and xterm's own encoder forwards wheel as SGR reports → tmux scrolls its OWN copy-mode history on wheel-up, auto-exits at bottom. The alt-scroll arrow conversion disappears too (tracking mode takes precedence). Desktop is fully fixed with no new endpoints.
+- **Touch**: still needs one small client change: in the touchmove path, when the active session is `shell` AND `mouseTrackingMode !== 'none'`, convert accumulated lines to `_sendSyntheticSgrWheel(x, y, lines)` instead of `scrollLines()`. The 40ms coalescing already prevents the tmux process storm (each send is a tmux send-keys server-side; unbatched flicks would spawn dozens of processes: this constraint is documented at `_sendSyntheticSgrWheel`, do not bypass it).
+- **Selection tradeoff to verify**: with tracking on, xterm hands drag events to tmux instead of doing local browser selection. Shift+drag still does local selection (xterm shift-override). Verify this UX on desktop before shipping; if it's unacceptable, fall back to approach (b).
+- **Also verify**: vim/less/htop inside the shell still behave (they'll now receive real mouse events via tmux, generally an improvement); remote shell sessions run tmux on the REMOTE host (`tmux -L codeman-remote`) and need the same option set there if remote shells are in scope (fine to defer, note it in the changeset if skipped).
+
+**Fallback approach (b), only if (a)'s selection tradeoff fails testing**: keep mouse off; when a shell session is in the alt buffer, have the client send scroll intents to a small server endpoint that drives `tmux copy-mode -e -t <pane>` + `send-keys -X -N <n> scroll-up/down`. Preserves selection semantics exactly, but needs a new endpoint, server-side batching, AND suppression of xterm's native alt-scroll arrow conversion (capture-phase wheel listener with `stopPropagation`, or `attachCustomWheelEventHandler` if the vendored xterm version has it). More moving parts; (a) should be tried first.
+
+**Not acceptable**: adding `shell` to `isAltScreenStripMode()`. vim/less/htop need the alt screen; that exclusion is deliberate and documented.
+
+### Bug C: mtiller's phone/iPad case — UNREPRODUCED, do not guess
+
+Touch is always-local by design, and Claude sessions keep content in the normal buffer (strip), so touch scrollback "should" work there. Before coding anything: build a repro matrix (iPhone Safari / iPad Safari / Android Chrome × claude / shell) on the current release. Plausible candidates if it does reproduce: auto-scroll-to-bottom fighting user scrolls (`_noteTerminalUserScroll`, ~line 2004), or they were in shell sessions on mobile too (then Bug B covers it). Ask mtiller on #205 for session mode + Codeman version if the matrix comes up clean.
+
+## Invariants the implementation MUST respect
+
+- Shift+wheel always scrolls local scrollback; the trackpad Shift-axis handling from #154 stays.
+- The `terminalWheelLocalScrollback` opt-out setting keeps working (pins plain wheel to local).
+- The viewport-at-bottom gate stays: once the user scrolled up locally, wheel stays local until they return to bottom.
+- 40ms SGR coalescing: never send per-event writes to the server.
+- Strip parity triangle: `session.ts` live strip ↔ `session-routes.ts` replay strip ↔ `_sessionUsesServerMouseStrip()` in the frontend. If you touch mode lists, update all three.
+- Don't add `opencode`/`antigravity` to any strip/forward list; their TUI wheel behavior is unverified (documented at `_shouldForwardWheelToApp`).
+- The chunk-boundary sequence carry in `_handleTerminalOutput` must not be weakened.
+
+## Testing (per repo rules)
+
+- `npm test -- test/<file>.test.ts` only; never bare `npm test`. New test ports 3150+, never 3000.
+- Browser-test traps (documented in CLAUDE.md Testing): drive input/scroll through real events (`page.mouse.wheel`, real touch), not app internals; headless Chromium reports `isTouchDevice()` false even with `hasTouch: true`; assert on real state (xterm viewport position, `tmux -L codeman capture-pane`), not HTTP 200.
+- Shell-mode E2E: create a throwaway shell session, `seq 1 500`, then (1) wheel up on desktop shows earlier lines, not history cycling; (2) touch-scroll on a phone shows earlier lines; (3) `vim` + `less` still enter/leave the alt screen cleanly; (4) Shift+drag still selects text.
+- Firefox E2E: Playwright `firefox` project, wheel over a Claude session's finished output, assert viewport moved more than 1 line per notch.
+- End-to-end against the REAL environment before claiming done (standing user rule). w1/w2/w3 tmux sessions are the user's live sessions: never send input to them; create your own throwaway session and DELETE it by exact id when done.
+
+## Related observation (not a reported bug, worth a look while in there)
+
+The `claude --version` probe that feeds the forwarding gate runs only for local and docker sessions (`src/session.ts:1490` gates `!this._remote`; docker handled at :1507). Remote Claude sessions therefore never get `cliVersion` and silently keep local-only wheel. Harmless (local scrollback works) but inconsistent; cheap to fix by probing over ssh, or document as intended.
+
+## Rollout
+
+1. Bug A (deltaMode) is small and independent: can ship alone as a patch.
+2. Bug B (shell scrollback) is the headline fix for #205: patch or minor per COM flow.
+3. After deploy + verification: comment on #205 (what was fixed, what needs their retest), then reply to the Reddit comment `p21x6ts` with the release version. Both reporters gave environment details; address them specifically.

docs/scrollback-issues-analysis.md

@@ -0,0 +1,255 @@
+# Scrollback issues: analysis and test evidence
+
+Covers GitHub issue **#205** ("Scrollback in terminal not working", jonocodes, shell mode,
+Android + macOS desktop) and the follow-up comment on it from **mtiller** (Firefox on macOS,
+"scrolling backward to see agent output"). Related closed issue: **#154** (fixed in 1.3.3).
+
+Status: **analysis only, nothing implemented.** Measured against the live 1.11.2 instance on
+2026-08-06 with throwaway `zz-*` shell sessions (all deleted afterwards; the user's `w*`
+sessions were never touched).
+
+---
+
+## TL;DR
+
+Five distinct problems, not one. #205 is fully explained by finding 1; findings 2 and 3 are
+independent and hit **every** mode including Claude, and are the likely substance of the
+"similar issue" follow-up.
+
+| # | Problem | Modes affected | Severity | Confirmed |
+| - | ------- | -------------- | -------- | --------- |
+| 1 | xterm parked in the **alternate buffer** for the whole session, so there is no scrollback at all and the wheel is translated into Up/Down arrow keys | `shell`, `opencode`, `antigravity` | High | Reproduced end to end |
+| 2 | **Bursty output silently destroys a screenful** of the browser's scrollback and adds ~1 row | all | High | Measured |
+| 3 | **Tab switch collapses scrollback** to roughly one screen (`full=1` fires once per page load) | all | Medium | Measured |
+| 4 | `deltaMode` is never read, so Firefox scrolls ~4x slower per notch | all, Firefox | Low | Static, needs reporter data |
+| 5 | **Remote SSH Claude cases get no `claude --version` probe**, so wheel forwarding silently stays off (residual #154) | `claude` + remote | Medium | Static |
+
+---
+
+## Finding 1: shell / opencode / antigravity are stuck in xterm's alternate buffer
+
+### Root cause
+
+The local tmux **client** (the `tmux attach` that node-pty spawns) emits `smcup` as its very
+first bytes on attach. Captured from a real PTY:
+
+```
+b'\x1b[?1049h\x1b[22;0;0t\x1b[?1h\x1b=\x1b[H\x1b[2J\x1b[?12l\x1b[?25h\x1b[?1000l...'
+ ^^^^^^^^^^ enter alternate screen              ^^^^^ application cursor keys ON
+```
+
+`Session._handleTerminalOutput()` strips `\x1b[?1049h` from the live stream, but only when
+`isAltScreenStripMode(mode)` is true, and that is `claude | codex | gemini` only
+(`src/session.ts:179`). For `shell`, `opencode` and `antigravity` the sequence reaches the
+browser verbatim and xterm switches to the alternate buffer, where:
+
+1. `buffer.active.type === 'alternate'` and `baseY` is pinned at 0, so there is **no
+   scrollback to reach**. `terminal.scrollLines()` is a no-op, which is why touch scrolling
+   on Android "does nothing".
+2. xterm's own wheel listener takes over. From the vendored bundle
+   (`src/web/public/vendor/xterm.min.js`):
+
+   ```js
+   if (!this.buffer.hasScrollback) {
+     if (ev.deltaY === 0) return false;
+     if (coreMouseService.consumeWheelEvent(...) === 0) return this.cancel(ev, true);
+     const seq = ESC + (decPrivateModes.applicationCursorKeys ? 'O' : '[') + (ev.deltaY < 0 ? 'A' : 'B');
+     coreService.triggerDataEvent(seq, true);
+     return this.cancel(ev, true);
+   }
+   ```
+
+   tmux also set `\x1b[?1h`, so the emitted sequence is `\x1bOA`, i.e. **Up arrow**, straight
+   into the shell's readline. That is exactly the reported "the mouse wheel scrolls back
+   through previous commands, like pressing up".
+
+3. `cancel(ev, true)` calls `preventDefault()` **and `stopPropagation()`**, and xterm's
+   listener sits on `terminal.element` (a child of Codeman's container). So Codeman's own
+   container wheel handler, `_shouldForwardWheelToApp` and `_wheelScrollLines` included, is
+   **never reached** for these modes. That whole path is dead code for shell.
+
+### Reproduction (live instance, real browser)
+
+Create a shell session with the page already open, print 150 lines, then dispatch 8 wheel-up
+events over `.xterm-screen`:
+
+```
+t+1500 after shell start       {"type":"alternate","length":35,"baseY":0}
+t+3000 after shell start       {"type":"alternate","length":35,"baseY":0}
+after 150 live lines           {"type":"alternate","length":35,"baseY":0}
+WHEEL on live shell: {"ptyBytes":["OA","OA","OA","OA",
+                                  "OA","OA","OA","OA"],
+                     "before":0,"after":0,"type":"alternate"}
+```
+
+Both reported symptoms, one root cause.
+
+### Why it looks intermittent
+
+The alternate-screen sequence only ever reaches the browser through the **live stream at
+attach**. Neither replay path carries it:
+
+- `?full=1` returns `capture-pane` output (`source: mux-full-history`), verified 0 hits for
+  `\x1b[?1049h`.
+- `?tail=` returns the visible pane frame (`source: mux-visible`), also 0 hits; the shell byte
+  buffer was empty in every probe.
+- `_resetTerminalForReplay()` calls `terminal.reset()`, which returns xterm to the normal
+  buffer.
+
+So: watching a shell from creation leaves you in the alternate buffer until you reload or
+switch tabs, at which point it silently starts working again. Then the next PTY attach (a
+restart, or the auto-reattach in `selectSession()`) puts you back.
+
+### Is stripping safe for shell? Probably yes when tmux-backed, and the current code comment is wrong about why
+
+`src/session.ts:1404` says *"shell must keep the alt screen for vim/less/htop"*. For a
+**tmux-backed** shell that reasoning does not hold: tmux is a full terminal emulator and never
+forwards a pane's alternate-screen toggles to its client, it repaints instead. Measured per
+phase on a real attach:
+
+| phase | bytes | `?1049h` | `?1049l` | `?47/1047` |
+| ----- | ----: | -------: | -------: | ---------: |
+| attach | 772 | **1** | 0 | 0 |
+| `seq 1 60` echo | 1402 | 0 | 0 | 0 |
+| `less` open / end / quit | 284 / 230 / 321 | 0 | 0 | 0 |
+| `vim` open / quit | 2200 / 646 | 0 | 0 | 0 |
+
+`vim` and `less` inside tmux emit **zero** alternate-screen sequences to the client.
+
+The caveat that does matter: `startShell()` falls back to a **direct PTY with no tmux** when
+mux creation fails (`src/session.ts:1961`, `this._useMux = false`). In that path the inner
+app's own `?1049h` does reach xterm, and a blanket strip would break vim/less/htop for real.
+Any fix has to be conditional on `_useMux`, which is known server-side.
+
+Second caveat: stripping alone buys less than it looks like, because of finding 2. It fixes
+the wheel (no more phantom Up arrows) and it makes the `full=1` replay reachable, but live
+output still will not accumulate.
+
+---
+
+## Finding 2: bursty output silently overwrites a screenful of browser scrollback
+
+Independent of the alternate buffer, and it hits Claude sessions too.
+
+tmux decides per flush whether to emit real linefeeds (which push rows into the outer
+terminal's scrollback) or to repaint the pane rectangle with cursor addressing (which
+overwrites the visible rows in place). When output outpaces its flush interval it coalesces
+into a repaint, and one screenful of the browser's history is **destroyed**.
+
+Measured on one session, same page, `rows = 36`:
+
+| step | `baseY` | rows containing SEED | BURST | SLOW |
+| ---- | ------: | -------------------: | ----: | ---: |
+| after `?full=1` replay (120 seeded lines) | 86 | 120 | 0 | 0 |
+| after 60 lines emitted as fast as possible | **87** (+1) | **86** (-34) | 35 | 0 |
+| after 60 lines at ~16/s (`sleep 0.06`) | **148** (+61) | 86 | 35 | 60 |
+
+The burst added **one** row of scrollback and ate **34** rows of existing history. The slow
+run behaved correctly. So "I printed a bunch of lines and now I cannot scroll back" reproduces
+without the alternate buffer being involved at all, and it is rate dependent, which is exactly
+the kind of thing that reads as random flakiness.
+
+Consequence: the browser's scrollback is effectively frozen at whatever the last `?full=1`
+replay produced, minus a screen per burst. tmux's own history is fine throughout
+(`history_size` kept growing, `history-limit` 2000), so the data is never actually lost
+server-side, it just never reaches the browser again until a reload.
+
+---
+
+## Finding 3: switching tabs collapses a session's scrollback
+
+`_initialFullBufferLoad` is true for the **first buffer load after a page load only**
+(`app.js:4374`). Everything after that uses `?tail=`, which returns byte history plus the
+visible pane frame. Worse, the snapshot restore path deliberately throws away the restored
+xterm snapshot (which does carry scrollback) and replaces it with that frame
+(`app.js:4316-4328` plus `needsRewrite`).
+
+Measured, switching away from session A and back:
+
+```
+A: initial full=1 load           {"len":152,"baseY":116,"AAA":150}
+A: after switch away and back    {"len": 87,"baseY": 51,"AAA": 59}
+```
+
+150 lines of history down to 59. Note also that the page's single `full=1` is consumed by
+whichever session auto-selects at load, so **every other tab starts life with one frame of
+history**.
+
+---
+
+## Finding 4: `deltaMode` is never read (Firefox)
+
+`grep -rn "deltaMode" src/web/public packages` returns nothing. `_wheelScrollLines()`
+(`terminal-ui.js:2818`) treats `deltaY` as pixels unconditionally:
+
+```js
+return Math.round(delta / 25) || (delta > 0 ? 1 : -1);
+```
+
+Chrome/WebKit report `deltaMode: 0` with `deltaY` around 100 to 120 px per notch, so about 4
+to 5 lines. Firefox reports `deltaMode: 1` (`DOM_DELTA_LINE`) with `deltaY` around 3, so
+`Math.round(3/25) === 0` and the `|| ±1` fallback yields **1 line per notch**, roughly 4x
+slower. In Claude mode the same value caps the forwarded SGR report at 1 tick per event
+instead of 4, so the transcript crawls too.
+
+This is sluggishness, not breakage, so it is a plausible but unproven contributor to the
+mtiller report. No Firefox build is installed under `~/.cache/ms-playwright` (chromium and
+webkit only), so this was not measured. Worth asking the reporter for `deltaMode` / `deltaY`
+from a live wheel event before acting on it.
+
+---
+
+## Finding 5: remote SSH Claude cases still have no version probe
+
+`src/session.ts:1490` deliberately skips the deterministic `claude --version` probe for
+remote sessions and defers to the startup-banner scrape, which the same comment block
+describes as unreliable ("newer Claude Code builds don't print the banner and resumed sessions
+never show it"). That is precisely the condition #154 was filed for: `cliVersion` empty means
+`_shouldForwardWheelToApp()` returns false, wheel forwarding is off, and the user is left with
+local scrollback that (per finding 2) does not accumulate.
+
+Local and Docker Claude sessions are fine; verified all 7 live sessions report
+`cliVersion=2.1.223`, so the 1.3.3 fix is still working there.
+
+---
+
+## Candidate directions (not decided)
+
+Roughly in order of value per unit of risk.
+
+1. **Extend the alternate-screen strip to tmux-backed `shell` / `opencode` / `antigravity`.**
+   Gate on `_useMux` so the direct-PTY fallback keeps vim/less/htop working. Kills the phantom
+   Up arrows and makes replayed history reachable. `isAltScreenStripMode()` currently takes
+   only `mode`, so it would need the mux flag threaded in, and
+   `test/claude-scrollback-strip.test.ts:16-17` plus `test/antigravity-mode.test.ts:116` pin
+   the current answers and would need updating.
+
+2. **Re-pull `?full=1` when the user scrolls to the top of the buffer.** Directly addresses
+   findings 2 and 3 with machinery that already exists and is already proven to return
+   complete history (200/200 lines in the probe). Needs a guard against refetch storms.
+
+3. **Stop discarding the xterm snapshot on tab switch**, or request `full=1` on the first load
+   per session rather than per page. Cheaper partial fix for finding 3 alone.
+
+4. **Read `ev.deltaMode`** in `_wheelScrollLines()` and normalise line/page deltas to lines.
+   Small, self-contained, worth doing regardless of whether it is mtiller's actual bug.
+
+5. **Probe the CLI version over SSH for remote Claude cases**, mirroring the deferred
+   in-container probe that Docker cases already use.
+
+Option 1 alone does not fix #205's "print a bunch of lines then scroll" complaint; that needs
+2 as well.
+
+## Reproduction assets
+
+Scripts used, in the session scratchpad
+(`/tmp/claude-1000/-home-arkon-default-claudeman/597ffc9f-.../scratchpad/`):
+
+- `ptycap.py` / `ptycap2.py`: PTY-level capture of the tmux client stream, per phase counts of
+  alternate-screen and mouse-tracking sequences.
+- `sim.mjs`: replays a captured stream through `@xterm/headless` with and without the strip.
+- `browser-test*.mjs`: Playwright against the live instance, reports `buffer.active.type`,
+  `baseY`, row content and the exact bytes xterm sends to the PTY on a wheel event.
+
+`@xterm/headless` was installed with `npm i --no-save`, so `package.json` and the lockfile are
+untouched.

docs/security-architecture.md

@@ -125,7 +125,9 @@ loopback bind matters. The auth pipeline (`src/web/middleware/auth.ts`,
 `onRequest` hook) runs in this order:
 
 1. **Localhost‑only exemptions** (always first): `POST /api/hook-event` and the QR
-   `/q/` short‑code path are exempt when `req.ip` is loopback (see §3). While the
+   `/q/` short‑code path are exempt when `req.ip` is loopback (see §3). The three
+   web‑tab exemptions (§10b: the capability in the path, the `Referer` form, and
+   the lost‑frame recovery page) sit in this same slot, ahead of the credential checks. While the
    **managed tunnel is running**, the hook‑event exemption additionally requires
    the per‑instance `X-Codeman-Hook-Secret` header (COD‑54); failed presentations
    are rate‑limited in a **dedicated bucket** (separate from Basic‑Auth failures)
@@ -268,9 +270,15 @@ tailscale serve --bg 3000      # HTTPS at https://<node>.<tailnet>.ts.net
 Only devices on your tailnet can reach it; Tailscale handles identity and
 terminates TLS with a real Let's Encrypt certificate (so PWA install and web
 push work). No app password and no `0.0.0.0` bind required. (This is the
-maintainer's production setup.) `CODEMAN_TAILSCALE=1` presets the choice for
-automation; the installer never runs `tailscale serve reset` and never touches
-serve mappings other than `443 -> Codeman's port`.
+maintainer's production setup.) `CODEMAN_TAILSCALE=1` or `--tailscale` presets
+the choice for automation. When `:443` on the node already belongs to another
+app, the installer mounts Codeman under `/codeman` (`tailscale serve --set-path`
+plus `--base-url`, which keeps the loopback bind and the same host guard) or on a
+second port rather than replacing it. The installer never runs `tailscale serve
+reset`, never touches serve mappings other than the one it created, never opens a
+`tailscale funnel` (public internet, a different risk class) and never advertises
+a Tailscale Service. Renaming the node (`--name`, `install.sh name`) is opt-in
+and defaults to no, because the tailnet name is also the machine's SSH identity.
 
 ### B. Authenticated cloudflared tunnel + password
 
@@ -312,8 +320,8 @@ TOCTOU window.
 | Route | Cap | Notes |
 |-------|-----|-------|
 | `file-content` | 10 MB | text preview |
-| `file-raw` | 50 MB | inline MIME map; **`X-Content-Type-Options: nosniff` on all responses** |
-| `POST /api/download` | 50 MB | forced `attachment`; sensitive‑path blocklist |
+| `file-raw` | 2 GB (`CODEMAN_MAX_DOWNLOAD_BYTES`, `0` = unlimited) | inline MIME map; **`X-Content-Type-Options: nosniff` on all responses**; streamed, `Range`-aware (206 slices come from the same validated path, and the cap is checked before the range) |
+| `GET /api/download` | same cap | forced `attachment`; sensitive‑path blocklist; streamed, `Range`-aware |
 
 ### SVG / content‑type XSS
 
@@ -340,7 +348,7 @@ the attachment guard below.
 
 Live external attachments (`src/attachment-registry.ts`) mint an `att_<uuid>` id
 for a host file so browser requests carry the id, never an absolute path. Serving
-is by id (`GET /api/sessions/:id/attachments/:attachmentId/raw`, 50 MB cap,
+is by id (`GET /api/sessions/:id/attachments/:attachmentId/raw`, same download cap,
 `nosniff`) and re‑resolves the symlink + re‑checks the **attachment guard**
 (`src/config/attachment-guard.ts`: the shared sensitive‑path blocklist **plus**
 the `/root` and `/etc` trees, extendable via `attachmentBlockedPaths` /
@@ -489,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`, `~/.config/{gcloud,opencode}`) 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.
@@ -508,17 +516,19 @@ 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).
 
 ---
 
 ## 10b. Web tabs (dashboard proxy)
 
-A saved dashboard URL renders as a tab, served through Codeman's own origin at `/webview/<capability>/`. User guide: [`web-tabs.md`](web-tabs.md). Three properties carry the security weight:
+A saved dashboard URL renders as a tab, served through Codeman's own origin at `/webview/<capability>/`. User guide: [`web-tabs.md`](web-tabs.md). Four properties carry the security weight:
 
 - **The proxy is exempt from cookie auth and the Origin/CSRF guard, and that is deliberate.** The iframe is sandboxed without `allow-same-origin`, so it is opaque‑origin: its requests are cross‑site, meaning the `SameSite=lax` session cookie is never attached and its writes and WS upgrades arrive with `Origin: null`. The credential is instead a 192‑bit capability in the path, minted only by an authenticated `POST /api/webviews/:id/open`, held in memory (a restart invalidates every one), rolling TTL, bound to the minting user, and granting nothing but "relay bytes to this one saved URL". ⚠️ **The Host allowlist is NOT bypassed**, so DNS‑rebinding protection is unaffected. A second `Referer`‑keyed form exists for root‑absolute assets and is the only exemption decided by a request‑supplied header, so it is fenced to safe methods on non‑`/api`, non‑`/ws`, non‑`/q` paths. Edges pinned by `test/webview-auth-exemption.test.ts`.
+- **The lost‑frame recovery page is the third unauthenticated 200, and the only one decided by request headers alone.** The proxy's runtime shim masks `/webview/<cap>/` off the page's own URL so a single‑page app routes on the path it expects; a navigation the page then starts itself (`location.reload()`, a root‑absolute `location.href`) lands on Codeman's root with no capability anywhere, no cookie (opaque origin) and a Referer naming the masked page. `serveLostWebviewFrame()` in `middleware/auth.ts` recognises it by shape (`GET`/`HEAD`, `Sec-Fetch-Dest: iframe` or `frame`, `Accept: text/html`, `Sec-Fetch-Mode: navigate` or absent) and answers, BEFORE the credential checks and without counting an auth failure, with a static page whose only content is a `postMessage` of the lost path to the parent tab (`default-src 'none'` plus the hash of that one script, `no-store`, `referrer: no-referrer`, no reflected input). It is fenced to paths that are NOT registered routes and never `/api/`, `/ws/` or `/q/`, with one carve‑out: `/` itself, because the landing page masks to exactly `/` and its reload otherwise rendered Codeman's app shell inside the web tab. `/` is admitted only when the request carries neither the `codeman_session` cookie nor an `Authorization` header: nothing in Codeman frames its own root and a sandboxed frame has neither, while a framed `/` that does carry credentials still gets the shell. On a passwordless install no auth hook runs, so the index route applies the same test itself (`isLostWebviewRootFrame`). ⚠️ Known property, accepted rather than mitigated: those headers are trivially set by a non‑browser client, so an unauthenticated caller can distinguish a registered route (401) from a non‑route (200) and enumerate the route table; the routes are public in `docs/api-reference.md`, so nothing is learned. Pinned by `test/webview-auth-exemption.test.ts` (password) and `test/webview-lost-root-frame.test.ts` (passwordless).
 - **Sandboxed by default; `allow-same-origin` is an explicit per‑dashboard opt‑in.** A proxied page is same‑origin with Codeman, so without the sandbox its JavaScript could read the Codeman document and call the agent‑spawning API. ⚠️ In BOTH modes the `Authorization` header and the `codeman_session` cookie are stripped before the upstream request, because a trusted (same‑origin) frame makes the browser attach Codeman's own Basic‑auth credentials to every proxied request; forwarding them would hand `CODEMAN_PASSWORD` to the dashboard.
-- **Not an open relay, and not a privilege boundary.** `resolveUpstreamUrl()` refuses anything leaving the saved origin, and cross‑origin redirects are handed back unchanged rather than followed. The proxy does reach whatever the SERVER can reach, which is not an escalation for someone who already commands `--dangerously-skip-permissions` agents, but in multi‑user mode it means a non‑admin's dashboard is fetched from the server's network position. Saved URLs are validated to plain http(s) with no embedded credentials, and there is deliberately **no magic‑link path**: terminal output can never create a webview (the mistake the attachment scanner had to be walled off from).
+- **Not an open relay, and not a privilege boundary.** `resolveUpstreamUrl()` refuses anything leaving the saved origin, and cross‑origin redirects are handed back unchanged rather than followed. The proxy does reach whatever the SERVER can reach, which is not an escalation for someone who already commands `--dangerously-skip-permissions` agents, but in multi‑user mode it means a non‑admin's dashboard is fetched from the server's network position. Saved URLs are validated to plain http(s) with no embedded credentials, and there is deliberately **no magic‑link path**: terminal output can never create a webview (the mistake the attachment scanner had to be walled off from). The one refused destination class is link‑local and cloud‑metadata addresses (`169.254.0.0/16`, `fe80::/10`, `fd00:ec2::254`, `168.63.129.16`, `100.100.100.200`, `metadata.google.internal`): `webview-egress-policy.ts` refuses them at save time, and `webview-egress.ts` re‑judges the RESOLVED address at connect time through a `lookup` hook on the proxy's undici Agent and on its WebSocket client, so a DNS name pointing into those ranges is refused as well. Loopback and RFC1918 stay allowed on purpose. Capabilities are revoked on logout, admin logout and user deletion, and proxied responses carry `Referrer-Policy: same-origin` so a dashboard cannot hand the capability‑bearing URL to a third‑party host it links.
 
 ---
 
@@ -529,6 +539,7 @@ A saved dashboard URL renders as a tab, served through Codeman's own origin at `
 | `CODEMAN_PASSWORD` (+ `CODEMAN_USERNAME`) | Enable HTTP Basic auth |
 | `--host` / `CODEMAN_HOST` | Bind host (default `127.0.0.1`) |
 | `CODEMAN_ALLOWED_HOSTS` | Extra `Host`/`Origin` allowlist entries for reverse proxies (comma‑separated; exact host, or leading‑dot `.suffix` for subdomains) — see §3 |
+| `--base-url` / `CODEMAN_BASE_URL` | Sub‑path prefix Codeman is mounted under behind a reverse proxy, e.g. `/codeman` (default `/`); the proxy must forward the prefix unchanged. Independent of `CODEMAN_ALLOWED_HOSTS` |
 | `--allow-unauthenticated-network` / `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK` | Acknowledge an unauthenticated non‑loopback bind (downgrades the warning) |
 | `--https` | Enable TLS (adds HSTS) |
 | `CODEMAN_INSTANCE` | Scope tmux socket + data dir for isolation |

docs/session-lineage-lines-plan.md

@@ -0,0 +1,246 @@
+# Session lineage lines (spawn lines between tabs)
+
+**Goal:** when a session spawns another session (the `codeman` agent skill starting a
+worker, or anything else that says who it is), draw the same kind of glowing connection
+line the subagent windows already use, but **tab → tab**, so a glance at the strip shows
+which tab spawned which.
+
+Status: PLAN. Nothing implemented yet.
+
+---
+
+## 1. The blocking fact: no parent relationship exists today
+
+There is no spawn-parent link between sessions anywhere in the codebase:
+
+- `SessionState` (`src/types/session.ts:388`) has no `parentSessionId` / `spawnedBy` /
+  `createdBy`.
+- `POST /api/quick-start` and `POST /api/sessions` record only `owner = ownerFor(req)`,
+  which is the multi-user **human**, not the calling session.
+- The only parent links that do exist are `TeamConfig.leadSessionId` (agent teams) and
+  `subagent-parents.json` (a frontend **window-layout** store for subagent windows).
+  Neither says "session A spawned session B".
+- Nothing in the HTTP request identifies the caller: an agent's spawn call is plain
+  `curl` from inside a tmux pane, so there is no socket-level identity to recover
+  (`SO_PEERCRED` needs a unix socket; the API is TCP).
+
+So the caller has to **tell** us. It already knows its own id: every managed pane gets
+`CODEMAN_SESSION_ID` exported by `session-cli-builder.ts` (and the skill's §0 preamble
+already binds it to `$SELF`).
+
+## 2. Wire format
+
+Two ways in, because they serve different callers. Body wins when both are present.
+
+| Where | Shape | Who uses it |
+| --- | --- | --- |
+| body field | `"parentSessionId": "<uuid>"` | anything hand-writing one create call |
+| request header | `X-Codeman-Parent-Session: <uuid>` | the skill: added **once** to the `CURL` array in the §0 preamble, so every present and future create call carries it with no per-recipe edit |
+
+Rules, all of them deliberate:
+
+- **Advisory decoration only.** It never grants access, never scopes anything, never
+  affects lifecycle. A child is not killed when its parent dies; the line just stops
+  being drawn once the parent tab is gone.
+- **Never fails a spawn.** An unknown / stale / foreign parent id is silently dropped
+  (field ends up `undefined`), not a `400`. A cosmetic field must not be able to break
+  worker creation.
+- **Resolved, not trusted.** The id must match a live session the caller can already
+  see (`canAccessOwned`), and the resolved parent's `owner` must equal the new
+  session's `owner`. Otherwise a user could staple their session under another user's
+  tab in multi-user mode.
+- Exact id match first; a `>= 8`-char **unique** prefix match as a fallback (ids appear
+  truncated in mux names and UI surfaces; ambiguous prefixes resolve to nothing).
+
+## 3. Server changes
+
+| File | Change |
+| --- | --- |
+| `src/types/session.ts` | `SessionState.parentSessionId?: string` with a doc comment saying it is UI decoration and never a permission signal |
+| `src/session.ts` | constructor option `parentSessionId` → `_parentSessionId`, public getter, emitted from `toState()` (~line 1170) |
+| `src/web/schemas.ts` | `parentSessionId: z.string().max(100).optional()` on `CreateSessionSchema` (272) and `QuickStartSchema` (680). Neither is `.strict()`, so this is additive |
+| `src/web/route-helpers.ts` | new `resolveParentSessionId(ctx, req, bodyValue, owner)` implementing §2's rules; returns `string \| undefined`, never throws |
+| `src/web/routes/session-routes.ts` | pass it into the three `new Session({...})` sites: `POST /api/sessions` (846), `POST /api/run` (2522), `POST /api/quick-start` (2896) |
+| `src/web/server.ts` | recovery path (~2617): `parentSessionId: savedState?.parentSessionId` so the link survives a restart |
+
+**No new SSE event.** `session_created` / `session_updated` broadcast
+`getSessionStateWithRespawn(session)`, which is `toState()`-derived, so the field rides
+along to the browser for free — and the frontend already does
+`this.sessions.set(data.id, data)`, so `session.parentSessionId` is simply there.
+
+Optional follow-up: surface it on `/api/sessions/unified` rows so the Session Manager
+and the home rails can show "spawned by w3-claudeman".
+
+## 4. Frontend rendering
+
+### 4.1 Where the code goes
+
+`_updateConnectionLinesImmediate()` (`subagent-windows.js:242`) is a strict
+**batched read → batched write** pass, and it already has an extension point:
+ultracode appends its own layer via `_appendUltracodeConnectionLines(svg, rects)` at
+the end, sharing the `rects` cache so no layer forces a second reflow.
+
+Lineage lines follow that exactly: a new module `src/web/public/session-lineage.js`
+(load order 15.6, after `ultracode-windows.js`) exporting
+`_appendLineageConnectionLines(svg, rects)` onto `CodemanApp.prototype`, called from the
+same tail. **The core function keeps ownership of the read/write split**; the new layer
+only reads through the shared `rects` map and only appends paths.
+
+The path math itself lives in `constants.js` as a pure
+`computeLineagePath(parentRect, childRect, stripRect, depth)` — same treatment as
+`computeTabScrollLeft`, so the geometry is unit-testable without a browser.
+
+### 4.2 Geometry
+
+Both endpoints are tabs in one horizontal strip, so the subagent shape (tab-bottom →
+window-top) does not apply. **One case**, a **U-bridge hanging below the strip** that
+touches both tabs on their bottom edge:
+
+```
+y0 = max(parent.bottom, child.bottom)
+d  = clamp(14 + |x2 - x1| * 0.085, 22, 104) + depth * 8 + |child.bottom - parent.bottom|
+path: M x1 parent.bottom  C x1 y0+d, x2 y0+d, x2 child.bottom
+```
+
+`depth` is the child's index among its siblings, so several children of one parent
+**nest** instead of overprinting.
+
+> **Superseded (2026-08-14): the two shapes this section used to specify.** The dip was
+> `clamp(14 + span * 0.06, 16, 44) + depth * 6`, and a wrapped strip
+> (`tabs-two-rows` / `tabs-auto-wrap`) got its own parent-bottom → child-**top** bezier.
+> Both were tuned against two tabs side by side and failed at the distances the feature
+> is used at:
+>
+> - a skill worker is appended to the **end** of the strip, so the real span is
+>   800-1500px, where a 44px cap is a 33px sag, i.e. a line that reads as straight and
+>   crosses the terminal instead of bracketing under the strip;
+> - and when the strip wraps, parent-bottom (34) to child-top (48) leaves **14px** to
+>   bend in, so the arc was a flat line hidden in the row gap, with siblings drawn on
+>   top of each other. Reported as *"they connect already, but the lines are straight
+>   and not easy visible"*.
+>
+> Anchoring both ends at the tab bottoms and hanging the control points below the
+> **lower** row gives the wrapped case the same bracket as the flat one, and removes the
+> branch. Pinned by `test/session-lineage-lines.test.ts`.
+
+A small `<circle r="3.5">` at the child end marks direction (it breathes to 4.5 while that worker is busy) (an SVG `marker` would need a
+`<defs>` block and fights `stroke-dasharray`).
+
+Each path gets `class="connection-line lineage-line"`, `data-parent-tab`,
+`data-child-tab`, and `data-agent-id="lineage:<childId>"` — that last one is what makes
+the existing entrance machinery (`markConnectionLineEntering` / `_applyLineEntrances`,
+keyed on `data-agent-id`) work on these lines with **zero** new animation code,
+including the negative-`animation-delay` resume across the `svg.innerHTML = ''` rebuild.
+
+### 4.3 Clipping
+
+`.session-tabs` is `overflow-x: auto`, so a tab scrolled out of the strip still has a
+rect — one that lies outside the strip box and would draw an arc across the logo or the
+header buttons. **Skip any edge whose parent or child center falls outside
+`stripRect` (4px tolerance).** Skipping is honest; clamping would draw a line to a tab
+that is not there.
+
+### 4.4 Redraw triggers
+
+`updateConnectionLines()` already coalesces through `scheduleBackground`, so extra
+callers are cheap. Needed:
+
+- `_fullRenderSessionTabs()` — already calls it (app.js:3912). Free.
+- `_renderSessionTabsImmediate()` — does **not**. A badge appearing widens a tab and
+  moves every tab after it, which slides the arcs off their anchors. Add the call,
+  guarded on `this._lineageEdgeCount > 0` so nobody pays for it without the feature.
+- **strip `scroll`** (passive listener on `#sessionTabs`) — the arcs must track the
+  scroller. This is new; no existing line layer needed it.
+- window `resize` — piggyback the throttled handler in `terminal-ui.js:930`.
+- `_onSessionCreated` — `markConnectionLineEntering('lineage:' + data.id)` so a new
+  child draws in **if** the user has a line-entrance theme on (all entrance styles are
+  `legacy`/off by default, so this is a no-op for an untouched install).
+
+### 4.5 Styling
+
+`.connection-line.lineage-line`: blue stroke from the per-skin `--session-blue` token
+(violet until 2026-08-14, changed because it lost contrast against the terminal's own
+dim foreground the moment the arc crossed text),
+`stroke-width: 2.5`, `dasharray 5 5`, `opacity: .72` (`.95` while the child works),
+softer than the subagent lines so the two layers still read as different things now that
+hue no longer separates them (shape does most of that work: a lineage arc hangs under the
+strip and never reaches a window), but the contrast against the terminal comes from a
+**second, wider glow** rather than more weight, because the first
+cut (2px / `4 4` / `.55` / one 5px glow) disappeared into terminal text on a real 1080p
+desktop. `lineage-flow` marches by two dash cycles, so it moves with the dash array
+(`5 5` → `-20`). Trap to respect: the skin block nests under
+`html:not([data-skin="og"])`, so a bare `.lineage-line` rule inside it would outrank the
+base rule at higher specificity. **Define the color as a token per skin, keep exactly
+one `.lineage-line` rule.** Light skins get a darker stroke.
+
+Optional signal worth having: `.lineage-line--working` (a slow `stroke-dashoffset`
+march) only while the **child** session is working, wrapped in
+`prefers-reduced-motion: no-preference`. Static otherwise — a permanently marching line
+per tab pair is noise and battery.
+
+### 4.6 Desktop only, and why
+
+The SVG overlay is `z-index: 999`. On desktop the header is `z-index: 100`, so arcs
+paint **over** the header and can touch tab bottoms. Under 1024px `mobile.css` makes the
+header `position: fixed; z-index: 1200`, which would **bury** the arcs — and the phone
+strip is a scroller where both endpoints are rarely on screen together anyway. So the
+layer returns early unless `MobileDetection.getDeviceType() === 'desktop'`.
+
+Raising the SVG to ~1250 (above the fixed header, below modals at 1300) is a possible
+phase 2, but it needs a real check against the mobile overview and the drawer.
+
+### 4.7 Setting
+
+`sessionLineageLines`, **per-device** — so it goes in the `displayKeys` set in
+`settings-ui.js` and must **not** be added to `SettingsUpdateSchema` (`.strict()`;
+sending an undeclared key fails the whole PUT). Rendered as a switch in
+App Settings → Appearance, beside the entrance-animation pickers.
+
+**Default: ON for desktop** (phones never render it). This is the one deliberate
+departure from the "new visual surfaces ship OFF" convention — the feature is the
+request, and a user with 12 unrelated tabs has a one-click off switch. Flag for the
+owner if the convention should win instead.
+
+## 5. Optional extras (call them separately, none are required)
+
+1. **Order children after their parent** in `sessionOrder` on create, so arcs stay short
+   and the strip reads as a tree. Real cost: it renumbers the Alt+N badges and moves
+   tabs under the user's cursor, so it should be its own toggle, default OFF.
+2. **Lineage hover focus**: hovering a tab dims unrelated arcs and brightens its own
+   subtree.
+3. **"Spawned by" in the Session Manager / home rails**, once `parentSessionId` is on
+   the unified rows.
+4. **Inherited tab tint**: children pick up a faded version of the parent's tab color.
+
+## 6. Tests
+
+- `test/session-lineage.test.ts` (route-level, `app.inject`): round-trips through
+  `POST /api/sessions` + `POST /api/quick-start`, header path, body-wins-over-header,
+  unknown id dropped without failing the spawn, cross-owner parent dropped in
+  multi-user, field present in `GET /api/sessions` and persisted state.
+- `test/session-lineage-lines.test.ts` (jsdom, pure): `computeLineagePath` — same-row U,
+  wrapped-row bezier, sibling nesting depth, off-strip skip, degenerate zero-width rects.
+- Browser check (not in `test:ci`): spawn two workers with a parent, assert two
+  `path.lineage-line` elements anchored to the right tabs, then scroll the strip and
+  assert they moved.
+- Existing guards that must stay green: `test/mobile-header-buttons-policy.test.ts`
+  (nothing new on phones), `test/app-settings-structure.test.ts` (the new switch pairs
+  with its rail section).
+
+## 7. Skill side (owned by the release session, not this plan)
+
+One line in the `codeman` skill's §0 preamble covers every spawn recipe:
+
+```bash
+CURL=(curl -sk "${AUTH[@]}" -H "X-Codeman-Parent-Session: $SELF")
+```
+
+plus a `CODEMAN_PREAMBLE` version bump so stale cached preambles fail loudly instead of
+silently spawning unparented workers. Recipes that build a create payload by hand can
+alternatively send `"parentSessionId":"'"$SELF"'"`.
+
+## 8. Docs to update when it lands
+
+`CLAUDE.md` (a Key Patterns bullet), `docs/architecture-invariants.md` (new anchor: the
+resolve-don't-trust rule, the desktop-only z-index reason, the shared `rects` pass),
+`docs/api-reference.md` (the new field + header on the create endpoints).

docs/split-pane-sessions-plan.md

@@ -0,0 +1,198 @@
+# Split-Pane Sessions — Design Spec
+
+**Status**: Implemented (v1)
+**Author**: Claude (session with Tim), 2026-09-15
+**Scope**: v1 only. v2 items are named and explicitly deferred, not designed.
+
+## Problem
+
+Codeman's terminal area shows exactly one active session (pane) at a time —
+switching panes re-binds the single xterm instance and the single WebSocket
+to a different session. Multi-monitor spanning (`scripts/span-codeman.sh` /
+`span-codeman.ps1`) turned out to solve a different problem: it makes one
+browser window bigger, but that window still shows one session; floating
+subagent windows are draggable overlays on top of it, not tiled panes. There
+is no way today to see two live sessions (e.g. `w1-codeman` and
+`w1-mcp-memory`) side-by-side in one window, even on a monitor wide enough to
+fit both.
+
+## Goal (v1)
+
+From the active session, open a **second, independent, fully live session**
+in a pane beside it — draggable divider, side-by-side only. Closing the
+second pane collapses back to today's normal single-pane view. No
+persistence: a page reload always returns to single-pane. Floating
+subagent/Ultracode windows keep their current behavior unchanged (global,
+unconstrained across the whole viewport, split or not).
+
+Explicitly out of scope for v1 (v2 candidates, not designed here):
+- More than 2 panes / grid layouts
+- Vertical (stacked) splits
+- Drag-a-tab-to-split as a trigger (v1 trigger is an explicit button + picker)
+- Persisting the split layout across reload or across devices
+- Mobile/tablet layouts (viewport is too narrow for this to make sense; gated
+  to desktop widths the same way `home-sessions.js`'s rail is)
+- Feature parity between the two panes (see "Pane B is deliberately plainer"
+  below)
+
+## Current architecture (why this isn't a CSS change)
+
+`terminal-ui.js` is built entirely around **singleton** state: `this.terminal`
+(one xterm instance), `this._ws`/`this._wsSessionId` (one WebSocket, rebound
+on every pane switch via `_disconnectWs()` + `_connectWs(newId)`), a
+`this._xtermSnapshots` map used only to restore scrollback into that one
+terminal when switching back to a session. Roughly 280 references to this
+singleton state exist across the file (input handling, resize/fit, sizing-
+token claims, mobile touch gestures, CJK IME, local-echo overlay wiring,
+keyboard accessory bar, link providers, etc.).
+
+Showing two sessions at once therefore requires a second, independently
+alive xterm + WebSocket pair running concurrently — not a layout change to
+one shared instance.
+
+**Related prior art**: `detachSession(id)` (app.js) already opens one session
+in a genuinely separate browser window (`isSoloWindow` mode) with its own
+independent WebSocket, and two of those can already be snapped side-by-side
+today with zero new code. That covers "two sessions visible at once" but not
+what this spec is for: one Codeman window with two panes and a divider you
+can drag without leaving your seat, each still a full participant in that
+window's floating subagent windows, header, and settings. This spec builds
+past detach, not a duplicate of it.
+
+**Server-side check (done, not just assumed)**: `MAX_WS_PER_SESSION = 5`
+(`src/web/routes/ws-routes.ts`), scoped by `clientId:tabNonce`
+(`ws-connection-registry.ts`). Splitting always opens a *different* session
+in the second pane (self-splitting is disallowed, see below), so this is two
+sessions each getting their normal one connection — the existing cap is
+irrelevant here and needs no server change.
+
+## Key design decision: Pane B is deliberately plainer than Pane A
+
+Porting all ~280 singleton behaviors to a second, symmetric pane is not
+worth it for v1 — most of that code is input-quality-of-life for **mobile/
+touch** (local-echo overlay, CJK IME textarea, touch gesture handling,
+keyboard accessory bar), and this feature is desktop-only by nature (a split
+view needs a wide viewport). So:
+
+- **Pane A** (the session that was already active when you opened the split)
+  stays exactly what it is today — `this.terminal`, `this._ws`, unchanged
+  code path, zero regression risk.
+- **Pane B** is a new, smaller `SplitTerminalPane` object: its own xterm
+  instance + fit addon, its own WebSocket to `/ws/sessions/:id/terminal`,
+  resize-on-divider-drag, and plain keyboard input. It does **not** get the
+  local-echo overlay, CJK IME composition, touch/mobile handlers, or the
+  keyboard accessory bar. On a desktop, typing directly into an xterm
+  instance with no overlay is exactly how Codeman behaved before the local-
+  echo overlay existed for touch devices — normal, not degraded, for a
+  keyboard-and-mouse user.
+
+If this asymmetry actually bothers you in daily use, promoting Pane B to full
+parity is a scoped v2 (extract the shared logic already once you have two
+call sites to compare, rather than guessing the right abstraction now).
+
+One more asymmetry worth naming here rather than discovering by surprise:
+while both panes accept keyboard input, the global capture-phase shortcut
+handler (`app.js`) always resolves against Pane A — it has no notion of
+which pane currently has focus. So Ctrl+L or Ctrl+W typed while Pane B has
+focus clears or closes Pane A, not the session you were actually typing
+into. Not fixed for v1, same reasoning as the rest of this section.
+
+## Components
+
+### 1. `SplitTerminalPane` (new, `terminal-split.js`)
+
+A small class, one instance per secondary pane:
+- `constructor(sessionId, mountEl)`
+- `connect()` — creates the xterm instance (same theme/font config as the
+  primary, read from the same settings so it doesn't visually clash), opens
+  `/ws/sessions/:id/terminal`, wires input → WS, WS → terminal write
+- `fit()` — calls the fit addon; called on divider drag (rAF-throttled) and
+  on window resize
+- `destroy()` — disposes the xterm instance, closes the WS cleanly
+
+No snapshot/scrollback-restore map is needed the way `_xtermSnapshots` exists
+for Pane A — Pane B is destroyed on close, not hidden-and-restored, since
+there's no persistence requirement.
+
+### 2. Split container (layout)
+
+```
+.terminal-split-container         (flex row, only rendered when split is active)
+├── .terminal-wrap                (existing element, Pane A — untouched)
+├── .split-divider                (new, draggable seam)
+└── .terminal-pane-b              (new, hosts SplitTerminalPane's xterm + a
+                                    small header: session name + × close button)
+```
+
+When not split, `.terminal-wrap` renders exactly as it does today (no
+wrapping container at all, to keep the no-split path byte-identical to
+current behavior). Splitting inserts the container and reparents
+`.terminal-wrap` into it as the first child — same reparenting pattern
+already used by `applySessionListLayout()` for `#sessionTabs`, so this isn't
+a new pattern for the codebase.
+
+Default split is 50/50 (`flex-basis: 50%` each). Divider drag updates both
+panes' `flex-basis` live (rAF-throttled) and calls `fit()` on **both**
+terminals per tick, clamped to 20%/80% so neither pane can be dragged into an
+unusably thin sliver.
+
+### 3. Trigger UI
+
+A **"Split"** button (header, opt-in like the other header buttons —
+`showSplitButton`, default off, same pattern as `showMultiMonitorButton`)
+opens a small picker listing your other open sessions (reuses
+`this.sessions`/`sessionOrder`, filtered to exclude the currently active
+session — you cannot split a session against itself). Picking one:
+1. Creates the split container, reparents `.terminal-wrap`
+2. Instantiates `SplitTerminalPane` for the chosen session in `.terminal-pane-b`
+3. Button state flips to "close split" (or Pane B's own header × does it)
+
+Closing (via Pane B's × or the header button toggling off):
+1. `SplitTerminalPane.destroy()`
+2. Removes `.terminal-split-container`, reparents `.terminal-wrap` back to
+   its original location at 100% width
+3. Fires a resize/fit on Pane A (same `ResizeObserver`-driven fit already in
+   place today — no new code needed here, it fires naturally once the
+   container's size changes)
+
+v2 note (not designed): dragging a session tab onto the active pane as an
+alternate trigger. You confirmed right-click doesn't work today (Codeman
+doesn't intercept it) and declined a keybind, so v1 is button+picker only.
+
+### 4. Failure / edge cases
+
+- **The Pane B session ends or is deleted while split is active** → treat
+  identically to the user closing Pane B manually: destroy the pane, collapse
+  to Pane A at full width.
+- **The Pane A session ends while split is active** → Pane B is promoted:
+  it becomes the new single full-width pane (reusing today's normal
+  single-pane code path means Pane B's `SplitTerminalPane` must hand off to
+  a real `this.terminal`/`this._ws` binding — simplest correct approach is
+  to just collapse the split and let normal session-select logic reopen
+  Pane B's session as the new primary, rather than trying to promote the
+  lightweight pane object in place).
+- **Both end** → falls through to today's normal "no active session" /
+  welcome-screen state.
+- **Subagent/Ultracode floating windows** → no design work needed; they're
+  already positioned independent of `.terminal-wrap`'s layout, so they
+  continue to float over whichever pane(s) are on screen, unconstrained,
+  exactly as today.
+
+## Testing
+
+- Unit: `SplitTerminalPane` connect/fit/destroy lifecycle (mock WS, like
+  existing terminal tests use `TEST_PTY_SCRIPT`).
+- Route/integration: opening two WS connections to two different sessions
+  from one simulated client concurrently — confirms the existing per-session
+  cap and connection registry need no changes.
+- Browser (Playwright, `test/browser` since this is desktop-viewport-gated
+  UI): open split via button+picker, verify both panes render live output
+  independently, drag divider and confirm both refit, close Pane B and
+  confirm Pane A returns to full width, kill the Pane B session externally
+  and confirm auto-collapse.
+
+## Open questions for review
+
+None blocking — the scope-narrowing decisions above (Pane B feature parity,
+no persistence, side-by-side only, button+picker trigger) came directly from
+your answers during brainstorming. Flag anything here you want reconsidered.

docs/tailscale-installer-plan.md

@@ -1,5 +1,10 @@
 # Tailscale Setup in the Installer (Plan)
 
+> Superseded in part by [`installer-v2-plan.md`](installer-v2-plan.md) (2026-09-20), which
+> moved every human step before the build, added the sub-path / second-port answer for an
+> occupied `:443`, the opt-in rename, flags, and the done screen with a QR code. The
+> state machine and safety rules below still hold.
+
 Goal: make "Codeman over Tailscale, with real HTTPS" a first-class, guided path in
 `install.sh`, instead of a one-line hint pointing at the docs. Today the safest
 recommended deployment (loopback bind + `tailscale serve`) is exactly what the

docs/terminal-anti-flicker.md

@@ -43,38 +43,22 @@ const syncData = DEC_SYNC_START + data + DEC_SYNC_END;
 this.broadcast('session:terminal', { id: sessionId, data: syncData });
 ```
 
-## Client-Side Implementation (`app.js`)
+## Client-Side Implementation (`terminal-ui.js`)
 
 ### `batchTerminalWrite(data)`
 
 1. Checks if flicker filter is enabled (optional, per-session)
 2. If flicker filter active: buffers screen-clear patterns (`ESC[2J`, `ESC[H ESC[J`, `ESC[nA`)
 3. Accumulates data in `pendingWrites`
-4. Schedules `requestAnimationFrame` if not already scheduled
-5. On rAF callback: checks for incomplete sync blocks (start without end)
-6. If incomplete: waits up to 50ms via `syncWaitTimeout`
-7. Calls `flushPendingWrites()` when complete
-
-### `extractSyncSegments(data)`
-
-- Parses DEC 2026 markers, returns array of content segments
-- Content before sync blocks returned as-is
-- Content inside sync blocks returned without markers
-- Incomplete blocks (start without end) returned with marker for next chunk
+4. Calls `_scheduleTerminalWriteFlush()` if no flush is pending
+5. The yielded callback clears its scheduled flag before calling `flushPendingWrites()`
+6. Large batches schedule their own next chunk until the queue is empty
 
 ### `flushPendingWrites()`
 
-```javascript
-const segments = extractSyncSegments(this.pendingWrites);
-this.pendingWrites = '';  // Clear before writing
-for (const segment of segments) {
-  if (segment && !segment.startsWith(DEC_SYNC_START)) {
-    terminal.write(segment);  // Skip incomplete blocks (start with marker)
-  }
-}
-```
-
-Note: Segments starting with `DEC_SYNC_START` are incomplete blocks awaiting more data. These are skipped (discarded if timeout forces flush).
+- Joins the queued terminal data and passes DEC 2026 markers through to xterm.js 6, which handles synchronized output natively.
+- Writes at most 32KB per yield for Codex and 64KB for other modes.
+- Requeues the remainder and immediately schedules another safe yield. A final large response therefore drains without waiting for another SSE event.
 
 ### `chunkedTerminalWrite(buffer, chunkSize=128KB)`
 
@@ -116,17 +100,15 @@ When detected, buffers 50ms of subsequent output before flushing atomically.
 
 ## Edge Cases
 
-- **Incomplete sync blocks**: 50ms timeout forces flush (content discarded to prevent freeze)
+- **Incomplete sync blocks**: xterm.js retains synchronized output until its closing marker
 - **Large buffers**: Chunked writing prevents UI freeze
 - **Server shutdown**: Skips batching via `_isStopping` flag
 - **Session switch**: Clears flicker filter state, pending writes, and sync timeout (prevents cross-session data bleed)
 - **SSE reconnect**: `handleInit()` clears all pending write state
 
-**Trade-off:** If a sync block is split across SSE packets and the end marker doesn't arrive within 50ms, the incomplete content is discarded. This prioritizes responsiveness over completeness. In practice this is rare since the server always sends complete `SYNC_START...SYNC_END` pairs and SSE typically delivers them atomically.
-
 ## DEC Mode 2026 Compatibility
 
-Terminals that natively support DEC 2026 will buffer and render atomically. Terminals that don't support it ignore the escape sequences harmlessly. xterm.js doesn't support DEC 2026 natively, so the client implements its own buffering by parsing the markers.
+Terminals that natively support DEC 2026 buffer and render atomically. Codeman uses xterm.js 6, so the client passes the markers through instead of parsing or discarding partial blocks.
 
 **Supporting terminals:** WezTerm, Kitty, Ghostty, iTerm2 3.5+, Windows Terminal, VSCode terminal
 
@@ -135,4 +117,4 @@ Terminals that natively support DEC 2026 will buffer and render atomically. Term
 | File | Key Functions |
 |------|---------------|
 | `src/web/server.ts` | `batchTerminalData()`, `flushTerminalBatches()`, `broadcast()` |
-| `src/web/public/app.js` | `batchTerminalWrite()`, `extractSyncSegments()`, `flushPendingWrites()`, `flushFlickerBuffer()`, `chunkedTerminalWrite()` |
+| `src/web/public/terminal-ui.js` | `batchTerminalWrite()`, `_scheduleTerminalWriteFlush()`, `flushPendingWrites()`, `flushFlickerBuffer()`, `chunkedTerminalWrite()` |

docs/terminal-copy-shortcut-plan.md

@@ -0,0 +1,303 @@
+# Terminal smart copy (Ctrl+C) plan
+
+Issue: [#211](https://github.com/Ark0N/Codeman/issues/211) "Terminal: Ctrl+C should copy when text is selected (interrupt otherwise)".
+Origin: r/selfhosted feedback, "Biggest stumbling block is apparent lack of copy-paste in the terminal."
+
+Status: **implemented and shipped** on 2026-08-05 (this document is kept as the rationale record). It was first served as an isolated beta over Tailscale for manual sign-off, then landed. Section 2 is the research that shaped the design, sections 4 to 6 describe what was built.
+
+---
+
+## 1. What the issue asks for
+
+- Text selected in the terminal + `Ctrl+C` -> copy the selection, toast, clear the selection, do NOT send the byte to the PTY.
+- No selection + `Ctrl+C` -> unchanged, the interrupt (`0x03`) reaches the PTY.
+- `Ctrl+Shift+C` as an explicit copy chord.
+- The selection check must run before the shortcut registry dispatch so a rebind cannot cost the user their interrupt key.
+- Paste is out of scope (it already works via `Ctrl+V`, which terminal-ui.js routes to the image/text paste trap).
+
+## 2. Verified current behavior
+
+### 2.1 xterm cancels the Ctrl+C keydown, so no copy can happen
+
+`src/web/public/vendor/xterm.min.js` (xterm 6.x), `_keyDown`:
+
+```js
+_keyDown(x){ if(this._keyDownHandled=!1, this._keyDownSeen=!0,
+  this._customKeyEventHandler && this._customKeyEventHandler(x)===!1) return !1;
+  ... evaluateKeyboardEvent(...) ... this.cancel(x) ... }
+```
+
+Two consequences that shape the design:
+
+1. The custom handler runs **first**, before xterm evaluates the key. Returning `false` exits before `cancel(x)`, so returning `false` does **not** call `preventDefault()` for us.
+2. When the handler returns `true`, xterm turns Ctrl+C into `0x03` and cancels the event, which is why the browser's own copy command never runs.
+
+Probe (headless chromium against an isolated server on port 3174, selection active, real focus on `.xterm-helper-textarea`, synthetic Ctrl+C keydown):
+
+```json
+{ "hasSelection": true, "defaultPrevented": true, "dataSeen": ["\"\\u0003\""],
+  "clipboardAfter": "SENTINEL-BEFORE", "stillHasSelection": false }
+```
+
+So today: interrupt byte sent, clipboard untouched, and xterm drops the selection anyway. The last point matters, "copy then clear the selection" is not a behavior change in how the selection feels, it is what already happens on any keypress.
+
+### 2.2 Why right-click Copy works today
+
+xterm registers a `copy` listener on its root element that substitutes the selection text:
+
+```js
+this._register(addDisposableListener(this.element,"copy",(k=>{ this.hasSelection() && copyHandler(k,this._selectionService) })))
+```
+
+Second probe (port 3175, real `page.keyboard.press('Control+c')`, custom handler patched to return `false` for Ctrl+C without `preventDefault`):
+
+```json
+{ "dataSeen": [], "copyEvents": ["xterm-element"],
+  "clipboardAfter": "native-copy-probe-line\n...", "stillHasSelection": true }
+```
+
+So a "return false and let the browser copy" implementation would also work in Chromium. It is rejected below (section 3.3) because it gives no toast, does not clear the selection, and leans on per-browser behavior of the copy command when the focused element is xterm's empty helper textarea.
+
+### 2.3 The document-level capture handler will not interfere
+
+`setupEventListeners()` in `src/web/public/app.js:989` runs on document capture, before xterm's textarea listener. Its registry loop skips any entry whose action is not in the local `SHORTCUT_ACTIONS` map:
+
+```js
+if (shortcut.disabled || !shortcut.action) continue;
+const action = SHORTCUT_ACTIONS[shortcut.action];
+if (!action) continue;
+```
+
+This is exactly how `command-palette` already behaves: it is a full registry entry (rebindable and disableable in App Settings) whose dispatch happens in a dedicated, focus-aware gate rather than the generic loop. The new copy entry follows that pattern, so the capture handler falls through untouched and the terminal handler owns the decision.
+
+### 2.4 Registry matching rules that constrain the bindings
+
+`matchesShortcutEvent()` (`app.js:4890`):
+
+- Ctrl and Cmd are interchangeable as the primary modifier, so a `['ctrl']` binding also matches Cmd+C on macOS. That is fine here: with a selection it copies (same result the native macOS path gives today), without one it falls through.
+- Every other modifier must be declared exactly: `if (mods.includes('shift') !== !!e.shiftKey) return false`. So `Ctrl+Shift+C` needs its own binding, a plain `ctrl+c` binding will never swallow it.
+- `binding.code` wins when present, otherwise `binding.key` is compared case-insensitively.
+
+### 2.5 Where selection is actually possible
+
+- The server strips mouse-tracking DECSETs for `claude`, `codex`, and `gemini` (`isAltScreenStripMode`, `src/session.ts:179`), which is why plain drag-select works in those tabs even though the TUI has mouse tracking on.
+- `shell`, `opencode`, and `antigravity` keep mouse reporting, so xterm requires `Shift`+drag to force a selection there. Worth one line in the docs, it is not a code change.
+- Touch devices deliberately disable selection entirely (`body.touch-device .terminal-container .xterm{user-select:none !important}`, `styles.css:3196`), and phones have no Ctrl key. This feature is desktop and hardware-keyboard only, with no mobile regression surface.
+
+### 2.6 Helpers that already exist and should be reused
+
+| Need | Existing code |
+| --- | --- |
+| Clipboard write with an HTTP-safe fallback | `_copyText(text)` in `app.js:1887` (Clipboard API, then hidden textarea + `execCommand`) |
+| Toast | `showToast(message, type)` in `panels-ui.js:4385` |
+| Translated string | `'Copied to clipboard'` already in `i18n.js:453` |
+| Focus-aware chord gate to copy the shape of | `shouldOpenCommandPaletteFromShortcut(e)` in `panels-ui.js:285` |
+| Buffer-wide copy (currently unreferenced) | `copyTerminal()` in `terminal-ui.js:2615` |
+
+`_copyText` matters more than it looks: `install.sh`'s LAN option serves plain HTTP, where `navigator.clipboard` is undefined. The issue's suggested `navigator.clipboard.writeText` alone would silently do nothing for those users, the `execCommand` fallback covers them.
+
+## 3. Design
+
+### 3.1 Behavior
+
+| Chord | Selection present | No selection |
+| --- | --- | --- |
+| `Ctrl+C` (and Cmd+C, per registry equivalence) | copy, toast, clear selection, swallow the key | fall through, xterm sends `0x03` (interrupt) |
+| `Ctrl+Shift+C` | copy, toast, clear selection, swallow the key | swallow, no-op (see 3.2) |
+| Shortcut disabled in App Settings | never copies, `Ctrl+C` is always the interrupt | unchanged |
+| Rebound to another chord | that chord copies when a selection exists | plain `Ctrl+C` is always the interrupt |
+
+### 3.2 Why `Ctrl+Shift+C` with no selection is swallowed rather than forwarded
+
+Today `Ctrl+Shift+C` produces `0x03` as well (the shift is irrelevant to the control byte), so forwarding would be "no regression". But once the chord is advertised as *the explicit copy key*, letting it interrupt a running agent when the selection happens to be empty is a footgun with no upside. Swallowing costs nothing: a user who wants to interrupt has `Ctrl+C` right there.
+
+The rule in code is "no selection and the matched chord had Shift -> swallow", not a hardcoded key check, so it stays correct under rebinds.
+
+### 3.3 Why an explicit clipboard write rather than falling through to the native copy
+
+Probe 2 showed the native path works in Chromium, but the explicit write is chosen because it:
+
+- gives the "Copied to clipboard" toast, which is the discoverability half of the issue,
+- clears the selection so a second `Ctrl+C` interrupts (the smart-copy contract),
+- works on plain-HTTP LAN installs through `_copyText`'s `execCommand` fallback,
+- does not depend on how each browser treats a copy command issued while an empty textarea has focus.
+
+### 3.4 Why no new app setting
+
+Per-shortcut enable/disable and rebinding already exist in App Settings -> Shortcuts and are driven by the registry. A user who wants "Ctrl+C is always interrupt" unchecks one box. Adding a `terminalSmartCopy` setting would duplicate that and would drag in the per-device vs synced decision (`displayKeys` + `.strict()` `SettingsUpdateSchema`) for no gain.
+
+## 4. Code changes, file by file
+
+### 4.1 `src/web/public/app.js`, registry entry
+
+Add to `DEFAULT_SHORTCUTS` (after the `clear-terminal` entry, ~line 351) so the Terminal group stays together:
+
+```js
+{
+  id: 'copy-selection',
+  group: 'Terminal',
+  label: 'Copy Selection',
+  bindings: [
+    { modifiers: ['ctrl'], key: 'c' },
+    { modifiers: ['ctrl', 'shift'], key: 'C' },
+  ],
+  // Dispatched by shouldCopyTerminalSelectionFromShortcut() in terminal-ui.js,
+  // deliberately NOT in SHORTCUT_ACTIONS: the generic capture loop always
+  // preventDefaults, which would cost the user the interrupt key.
+  action: 'copyTerminalSelection',
+},
+```
+
+Match on `key`, not `code`. xterm decides what byte to emit from the produced character, so intercepting the physical `KeyC` on a layout where it does not produce "c" would diverge from what xterm would have sent.
+
+The `action` string is required for App Settings to render the row as configurable (`configurable = !!shortcut.action && Array.isArray(shortcut.bindings)`, `settings-ui.js:2624`). Do **not** add `copyTerminalSelection` to `SHORTCUT_ACTIONS`.
+
+### 4.2 `src/web/public/terminal-ui.js`, the gate
+
+New prototype method, modeled on `shouldOpenCommandPaletteFromShortcut`:
+
+```js
+shouldCopyTerminalSelectionFromShortcut(ev) {
+  if (!ev || ev.type !== 'keydown') return false;          // the handler also runs for keypress/keyup
+  if (!ev.ctrlKey && !ev.metaKey && !ev.altKey) return false;  // hot path: plain typing exits here
+  const registryAvailable =
+    typeof this.getShortcutRegistry === 'function' && typeof this.matchesShortcutEvent === 'function';
+  const entry = registryAvailable
+    ? this.getShortcutRegistry().find((s) => s.id === 'copy-selection')
+    : null;
+  if (entry) return !entry.disabled && this.matchesShortcutEvent(ev, entry);
+  return (ev.key || '').toLowerCase() === 'c' && !ev.altKey; // fallback for isolated harnesses
+}
+```
+
+### 4.3 `src/web/public/terminal-ui.js`, the branch
+
+Inside `attachCustomKeyEventHandler` (`terminal-ui.js:133`), after the command-palette gate and before the `Ctrl+V` branch:
+
+```js
+// Smart copy (#211): with a selection, Ctrl+C copies instead of sending ^C.
+// With no selection it MUST fall through (return true, no preventDefault) or
+// the interrupt key is lost. Ctrl+Shift+C is the explicit chord and never
+// falls through: an "explicit copy" that interrupts the agent is a footgun.
+if (this.shouldCopyTerminalSelectionFromShortcut?.(ev)) {
+  const selection = this.terminal.hasSelection?.() ? this.terminal.getSelection() : '';
+  if (selection) {
+    ev.preventDefault();
+    void this.copyTerminalSelection(selection);
+    return false;
+  }
+  if (ev.shiftKey) {
+    ev.preventDefault();
+    return false;
+  }
+  return true;
+}
+```
+
+`preventDefault()` is explicit because returning `false` alone does not cancel the event (section 2.1), and without it the browser would run its own copy on top of ours.
+
+### 4.4 `src/web/public/terminal-ui.js`, the copy action
+
+```js
+async copyTerminalSelection(text) {
+  const selection = text ?? (this.terminal.hasSelection?.() ? this.terminal.getSelection() : '');
+  if (!selection) return false;
+  const ok = await this._copyText(selection);
+  if (ok) {
+    this.terminal.clearSelection?.();
+    this.showToast('Copied to clipboard', 'success');
+  } else {
+    this.showToast('Failed to copy', 'error');
+  }
+  // _copyText's execCommand fallback focuses a temp textarea; restore the
+  // terminal (this.terminal.focus is the CJK-aware router, not xterm's raw focus).
+  this.terminal.focus();
+  return ok;
+}
+```
+
+The selection text is captured **before** the first `await`, and `navigator.clipboard.writeText` is reached in the same task as the keydown, so user activation still holds.
+
+### 4.5 `src/web/public/i18n.js`
+
+`'Copied to clipboard'` exists. Add `'Failed to copy': '复制失败'` (the error path is new to this surface).
+
+### 4.6 Documentation
+
+| File | Change |
+| --- | --- |
+| `README.md` shortcut table (~line 648) | `\| `Ctrl/Cmd+C` \| Copy selection (interrupts when nothing is selected) \|` and a `Ctrl+Shift+C` row |
+| `src/web/public/index.html` help modal, Terminal section (~line 641) | `<div><kbd>Ctrl</kbd>+<kbd>C</kbd></div><div>Copy Selection / Interrupt</div>` plus the Ctrl+Shift+C row. Keep the existing negative assertion in `help-modal-shortcuts.test.ts` in mind (it forbids `Ctrl+K`, `C` is fine) |
+| `CLAUDE.md` "Keyboard shortcuts" line | add `Ctrl+C` (copy selection, else interrupt) and `Ctrl+Shift+C` |
+| `docs/architecture-invariants.md` -> "Command palette and shortcut registry" | append the invariant: the no-selection path must return `true` without `preventDefault`, the branch is keydown-only, and `copyTerminalSelection` must stay out of `SHORTCUT_ACTIONS` |
+
+The shortcut overlay (`Ctrl+?`) and App Settings -> Shortcuts are registry-driven and pick the entry up with no edit.
+
+## 5. Edge cases and risks
+
+| Case | Handling |
+| --- | --- |
+| Handler also fires for `keypress`/`keyup` | gated on `ev.type === 'keydown'`. xterm's `_keyPress` bails on ctrl combos anyway, so no stray byte |
+| CJK IME composing | the existing `isComposing || keyCode === 229` guard is the first line of the handler and stays first |
+| Local echo overlay has unsent `pendingText` | the copy branch returns before `onData`, so `pendingText`, flushed offsets and the durable input queue are untouched. The no-selection path is byte-identical to today, including the "control char flushes buffered text then sends `0x03`" logic at `terminal-ui.js:895` |
+| Plain HTTP (LAN install) | `_copyText` falls back to `execCommand`, then focus is restored |
+| Clipboard write rejected (permissions policy, no gesture) | error toast, right-click Copy still available |
+| Whitespace-only or empty selection | `getSelection()` empty string is treated as "no selection", so Ctrl+C still interrupts |
+| macOS Cmd+C | registry treats ctrl/meta as interchangeable, so with a selection it takes our path (same visible result as today's native copy), without one it falls through |
+| Chrome/Firefox `Ctrl+Shift+C` is the devtools inspect chord | browser-level and may still toggle devtools, our copy runs regardless. Document as a caveat, `Ctrl+C` is the primary path |
+| Selection in a tab whose TUI owns the mouse (`shell`/`opencode`/`antigravity`) | unchanged, `Shift`+drag selects, then Ctrl+C copies |
+| Web tab (iframe dashboard) focused | xterm handler never runs, browser-native copy inside the iframe |
+| Teammate/subagent terminals (`panels-ui.js:2268`, `onData` wired) | same limitation exists there, out of scope for this PR (section 8) |
+
+## 6. Test plan
+
+New file `test/terminal-copy-selection.test.ts` (node env, `vm` harness in the style of `test/command-palette-ui.test.ts`), covering `shouldCopyTerminalSelectionFromShortcut` in isolation:
+
+1. Ctrl+C keydown -> true, keyup/keypress of the same chord -> false.
+2. Ctrl+Shift+C -> true, plain `c` -> false, Ctrl+K -> false.
+3. Registry entry `disabled: true` -> false for every chord.
+4. Rebound entry (for example Alt+Y) -> true for the rebind, false for Ctrl+C.
+5. Missing registry (harness without `getShortcutRegistry`) -> falls back to the `c` check.
+
+Static assertions appended to `test/keyboard-shortcuts.test.ts` (this suite already pins the xterm-handler chokepoint):
+
+6. `DEFAULT_SHORTCUTS` contains `id: 'copy-selection'` and `SHORTCUT_ACTIONS` does **not** contain `copyTerminalSelection` (the interrupt-safety invariant).
+7. `terminal-ui.js` contains the `shouldCopyTerminalSelectionFromShortcut` branch and a `return true` no-selection fall-through.
+8. README + help modal rows exist (mirrors the existing palette/Alt-nav doc assertions).
+
+`test/help-modal-shortcuts.test.ts`: add `expectShortcut(helpModal, ['Ctrl', 'C'], 'Copy Selection')`.
+
+New browser test `test/terminal-copy-shortcut.test.ts` (Playwright, port **3174**, free per a scan of `test/`), following `test/webgl-fallback.test.ts`: boot `WebServer`, grant `clipboard-read`/`clipboard-write`, `terminal.write()` a known line, `selectLines()`, real `page.keyboard.press('Control+c')`, then assert clipboard content, empty `onData` capture, cleared selection and the toast. Second case: no selection, assert `onData` saw `\u0003` and the clipboard is unchanged.
+Per repo convention, browser suites are excluded from CI, so add the filename to the exclude list in `config/vitest.ci.config.ts` and run it locally.
+
+Regression runs: `npm test -- test/keyboard-shortcuts.test.ts`, `test/help-modal-shortcuts.test.ts`, `test/command-palette-ui.test.ts`, `test/input-send-order.test.ts`, then `npm run test:ci`.
+
+## 7. Manual verification before COM (CLAUDE.md rule)
+
+Against a throwaway session on the live instance (`curl -sk https://localhost:3000/...`, never w1/w2/w3):
+
+1. Select output with the mouse, press Ctrl+C, confirm the toast, paste elsewhere, confirm the agent did not stop.
+2. Press Ctrl+C again with nothing selected, confirm the agent interrupts.
+3. Type a few characters with local echo on (phone or `localEchoEnabled` forced), press Ctrl+C with no selection, confirm buffered text plus interrupt behave as before.
+4. Uncheck the shortcut in App Settings -> Shortcuts, confirm Ctrl+C always interrupts even with a selection.
+5. Rebind it, confirm the new chord copies and Ctrl+C reverts to pure interrupt.
+6. Repeat 1 and 2 in an `opencode` or `shell` tab using Shift+drag to select.
+7. Load over plain HTTP (`--host` LAN or `http://127.0.0.1:<port>`) and confirm the `execCommand` fallback copies and focus returns to the terminal.
+8. Mobile smoke: confirm nothing changed (selection is CSS-disabled, no Ctrl key).
+
+## 8. Out of scope, follow-ups worth filing separately
+
+- **Teammate/subagent terminals** (`panels-ui.js:2268`) have the same blocked-copy problem. One `attachCustomKeyEventHandler` reusing `copyTerminalSelection` would fix them, but it touches a different surface and deserves its own change.
+- **A mobile copy affordance.** Selection is disabled on touch, so phones still cannot copy terminal text. The unreferenced `copyTerminal()` (whole buffer) plus a keyboard-accessory "Copy" button would be the cheapest answer.
+- **Right-click context menu** with Copy/Paste, better discoverability than any chord, but a bigger UI surface.
+- **`copyTerminal()` cleanup**: it uses raw `navigator.clipboard` rather than `_copyText`, so it would fail on plain HTTP if ever wired up.
+
+## 9. PR mechanics
+
+- Branch off `master` (verify with `git branch --show-current`, the tree is shared), stage explicit paths only.
+- Files touched: `src/web/public/app.js`, `src/web/public/terminal-ui.js`, `src/web/public/i18n.js`, `src/web/public/index.html`, `README.md`, `CLAUDE.md`, `docs/architecture-invariants.md`, `docs/terminal-copy-shortcut-plan.md`, three test files, `config/vitest.ci.config.ts`.
+- `index.html`, `app.js` and `terminal-ui.js` are `.prettierignore`d hand-formatted assets, match the surrounding style by hand. `npm run check:public-assets` and `npm run check:frontend-syntax` are the guards.
+- No changeset in this PR: a merged, unconsumed changeset turns the Release workflow red until the next COM, and the COM flow writes release notes covering everything since the last tag (current version is 1.10.0).
+- Close #211 from the PR body.
+
+Rough size: about 60 lines of product code, most of the work is the tests and the four documentation surfaces.

docs/tui-plan.md

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

docs/tui.md

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

docs/usage-limits-display-plan.md

@@ -2,6 +2,8 @@
 
 > **Status: SHIPPED — deployed to prod + pushed to master, not yet released (2026-06-14).** App Settings → Display → **Plan Usage Limits** (`showPlanUsageLimits`). **Default changed in 1.9.3: desktop now defaults ON, handhelds stay OFF, resolved via `planUsageChipEnabled()`.** The per-device notes further down describing it as opt-in/synced record the original 2026-06-14 shape, not current behavior. Commits `c82f6c8` (feature) → `4d9d93d` (end-to-end fixes) → `eae225b` (per-user reconcile) → `95fb5fc` (init-snapshot replay). Full suite green (2869), CI green. No changeset/version bump yet.
 >
+> **2026-09-07 rework — the "Injection lifecycle" section below (disk-write reconcile via `applyStatusLineConfig`) is SUPERSEDED and describes the OLD mechanism, kept for history.** That disk write let a Codeman-marked `statusLine.command` in `.claude/settings.local.json` take precedence over the user's own global/project statusline for ANY `claude` run in that directory — including entirely outside Codeman — with no disclosure and no way to undo it (real bug, found 2026-08-31). The exporter is now injected as an EPHEMERAL `claude --settings` CLI flag at spawn (`resolveStatusLineCliCommand`/`ensureStatusLineExporterScript`, hooks-config.ts) — never written to disk — and it WRAPS the user's own real statusline (`findEffectiveUserStatusLineCommand`) rather than replacing it. `showPlanUsageLimits` now doubles as the telemetry COLLECTION switch too: `readPlanUsageTelemetryEnabled()` reads it fresh from `settings.json` at every claude session create/respawn (`TmuxManager.createSession`/`respawnPane`), so it applies uniformly across every claude-creation path — interactive Run, cron, the Ralph Loop API, quick-start — with no per-session state (a Codeman restart cannot silently kill it) and no per-request field on the wire at all. An absent key reads as ON (the reader resolves the default; `GET /api/settings` never writes), and a settings save carries the key only when it flips the chip on that device, so a handheld with the chip off cannot switch collection off for a desktop by saving something unrelated. The exporter prints nothing on failure rather than the bare word `codeman` (discussion #405).
+>
 > Two surfaces from one `statusLine` callback:
 > - **Header chip** (top-right) — account-wide **plan limits**: `5h 35% · 7d 38%`, per-window green/yellow/red.
 > - **In-terminal statusline footer** — the **current session's** status: `Opus 4.8 (1M context)  in:562,411 out:1,188  ctx:56%`.
@@ -110,33 +112,33 @@ Fixed path (sessionId in the **body**, not the URL) so the auth exemption is an
 2. **Fresh load / reconnect:** server stores the latest in `plan-usage-latest.ts`; `getLightState()` includes it as `planUsage`; the per-connection **init snapshot** replays it; `handleInit` paints the chip immediately (authoritative over localStorage). Null until the first telemetry of the process.
 3. **Offline / cross-restart:** `restorePlanUsageChip()` reads `localStorage` on load (12h freshness guard).
 
-### 5. Injection lifecycle — works for *any* user, never self-destructs
+### 5. Injection lifecycle (SUPERSEDED 2026-09-07 — see header note; kept for history)
 
 The setting `showPlanUsageLimits` is **synced** (in `settings.json`, not a per-device `displayKey`).
 
-- **On toggle** (`PUT /api/settings`, `system-routes.ts`): reconcile the exporter across **all active Claude sessions' working dirs** — inject on enable, remove on disable. Server-side and authoritative, so existing sessions get the footer + feed the chip *immediately*, no new session needed, no dependency on a client's synced localStorage.
-- **On session create** (`session-routes.ts`): **ADD-ONLY** — inject when `statusLineTelemetry` is true; **never remove**. Sessions in a repo share one `settings.local.json`, so a single create-with-false (e.g. a client whose synced setting hadn't loaded) must not yank the statusLine out from under other live sessions. Removal happens only via the explicit toggle.
-- `applyStatusLineConfig()` is **`isOurs`-guarded** (matches `/api/status-telemetry`), so a user's own hand-authored statusLine is never touched, and it **updates an out-of-date ours-command** so fixes (e.g. `-k`) propagate. **No `CASES_DIR` gate** — runs for linked cases / real repos (where sessions actually run), mirroring `updateCaseModel`.
+- ~~**On toggle** (`PUT /api/settings`, `system-routes.ts`): reconcile the exporter across **all active Claude sessions' working dirs** — inject on enable, remove on disable.~~ There is nothing to (re)inject into an already-running session under the new CLI-flag mechanism — the NEXT respawn (a Ralph cycle, `/clear`, a PTY-exit restart) already reads the setting fresh.
+- ~~**On session create** (`session-routes.ts`): **ADD-ONLY** — inject when `statusLineTelemetry` is true; **never remove**.~~ There is no `statusLineTelemetry` request field anymore. `TmuxManager.createSession`/`respawnPane` read `readPlanUsageTelemetryEnabled()` fresh at spawn instead, uniformly across every claude-creation path.
+- ~~`applyStatusLineConfig()` is **`isOurs`-guarded**~~ — `applyStatusLineConfig` still exists but only for the SELF-HEAL path now (`resolveStatusLineCliCommand` strips a legacy disk-written exporter the first time a session starts in a workspace an older Codeman build touched).
 
 ## Codeman-specific considerations
 
 1. **Account-global limits.** The 5h/7d pools are shared across all sessions on the account → one shared header chip (freshest sample wins), not a per-tab bar.
 2. **The footer is owned, by necessity.** A statusLine command always replaces Claude's default footer. Since `rate_limits` *only* arrives via statusLine, we reconstruct a useful **session-status** footer (model · tokens · ctx %) from the same payload rather than showing the limits there.
-3. **`isOurs`-guarded.** Never removes/overwrites a user's own statusLine on disable; only manages the Codeman exporter.
+3. **Never overwrites, now WRAPS.** The exporter composes with a user's own real statusline (`findEffectiveUserStatusLineCommand`) rather than replacing it; `applyStatusLineConfig`'s `isOurs`-guard now only backs the legacy self-heal removal path.
 4. **Security envelope unchanged.** The exporter runs arbitrary shell every render — same trust model as the hook curls (localhost + `$CODEMAN_HOOK_SECRET_FILE`); reuses the hook-secret gate.
-5. **Claude-only.** OpenCode/Codex emit no `rate_limits` JSON; injection is gated to `mode === 'claude'`.
+5. **Claude-only, registry-gated.** Injection is gated on `getCli(mode)?.capabilities.statusLineTelemetry` (currently `true` only for claude) rather than a hardcoded `mode === 'claude'` string.
 6. **Future — auto-resume synergy.** Live percentages would let `SessionAutoOps` pre-arm *before* the wall instead of reacting to the stall footer. Not built.
 
 ## Files shipped
 
 - `src/usage-telemetry.ts` — pure parse/format (`parseStatusTelemetry`, `parseSessionStatus`, `formatSessionStatusText`, `telemetrySignature`) + `test/usage-telemetry.test.ts`.
-- `src/hooks-config.ts` — `generateStatusLineCommand()` (`curl -sk`), `applyStatusLineConfig()` (add/update/remove, `isOurs`-guarded).
+- `src/hooks-config.ts` — `resolveStatusLineCliCommand()`/`ensureStatusLineExporterScript()` (ephemeral CLI-flag injection, never disk), `findEffectiveUserStatusLineCommand()` (wrap the user's real statusline), `readPlanUsageTelemetryEnabled()` (fresh global-setting read), `applyStatusLineConfig()` (legacy self-heal removal only now).
+- `src/session-cli-registry-bridge.ts` — merges the exporter path into the SAME `--settings` JSON object as effort/ultracode (Claude Code accepts only one `--settings` flag per invocation).
 - `src/web/routes/status-telemetry-routes.ts` — `POST /api/status-telemetry`.
 - `src/web/plan-usage-latest.ts` — process-wide last-known store for init replay.
-- `src/web/schemas.ts` — `StatusTelemetrySchema` + `showPlanUsageLimits` + create-payload `statusLineTelemetry`.
+- `src/web/schemas.ts` — `StatusTelemetrySchema` + `showPlanUsageLimits` (no separate create-payload or action field anymore).
 - `src/web/middleware/auth.ts` — exemption extended to `/api/status-telemetry`.
-- `src/web/routes/session-routes.ts` — add-only create-time injection.
-- `src/web/routes/system-routes.ts` — settings-toggle reconcile.
+- `src/tmux-manager.ts` — `createSession`/`respawnPane` read `readPlanUsageTelemetryEnabled()` fresh at spawn.
 - `src/web/server.ts` — `getLightState().planUsage` (init snapshot).
 - `src/web/sse-events.ts` + `constants.js` — `session:statusTelemetry`.
 - Frontend: `app.js` (`_onSessionStatusTelemetry`, `updatePlanUsageChip`, `restorePlanUsageChip`, `handleInit`), `settings-ui.js` (toggle + `applyHeaderVisibilitySettings`), `index.html` (chip + toggle row), `styles.css` (chip + colors), `session-ui.js` (create payload).

docs/vm-cases-plan.md

@@ -0,0 +1,201 @@
+<!-- Design doc drafted 2026-07-28 from WWDC26 session 224 research. STATUS: PLANNED, NOT IMPLEMENTED. Blocked on macOS 27 "Golden Gate" (beta now, GA expected fall 2026). -->
+
+# VM Cases (macOS Virtualization framework), Implementation Plan
+
+## Status
+
+PLANNED, nothing implemented. This is the design + phased execution plan for a native-macOS VM isolation tier for cases ("the VM subsystem"), modeled on Docker cases (`docs/docker-cases-plan.md`). Testbed prerequisite: a macOS 27 host (see Section 8).
+
+**⚠ DESIGN DIRECTION (owner, 2026-07-29): the subsystem is GUI-first.** Users want real macOS desktops, not headless SSH machines. Guests may be macOS (GUI-only in practice) or Linux (GUI or headless). Key decision 3 below carries the full consequences; anything in this doc that reads as "Linux-first / headless-first" predates this and has been revised.
+
+**2026-07-29: Phase 0 substantially validated on the beta testbed; full Apple-stack reference now lives in [`docs/vm-subsystem-apple-stack.md`](vm-subsystem-apple-stack.md)** (API surfaces, beta bugs, our empirical results, and design implications). Plan-relevant corrections from that work: vmnet's topology/port-forwarding APIs are macOS 26 (only the loopback fix is 27); guest provisioning is macOS-guests-only (Linux stays cloud-init, proven working); DiskImageKit has NO flatten/merge, so the `export` subcommand ships the layer chain (or flattens in-guest) instead of flattening; seed ISOs are base-build-time only, never attached at case runtime; per-case EFI variable stores are mandatory; guest health checks read DHCP leases, never serial/ping.
+
+## 1. Context and motivation
+
+WWDC 2026 session 224 ("Expand the Capabilities of your Virtualization App", https://developer.apple.com/videos/play/wwdc2026/224/) shipped the missing pieces for programmatic, fleet-style VM management on macOS:
+
+- **`VZMacGuestProvisioningOptions`**: automated first-boot setup of a macOS guest (user account, auto-login, SSH enabled) with zero interactive setup.
+- **DiskImageKit**: stacked disk images on the Apple Sparse Image Format (ASIF): a read-only base layer plus cheap per-VM cache/overlay layers. Direct analog of Docker image layers + writable container layer.
+- **vmnet framework**: custom network topologies and port forwarding from the host process.
+- **`VZCustomVirtioDevice`**: custom low-latency host<->guest channels (Linux guests).
+- **AccessoryAccess**: USB passthrough (not relevant to Codeman, out of scope).
+
+Codeman's isolation story today is Docker cases. On macOS, Docker means Docker Desktop / a Linux VM anyway, with weaker fidelity and a heavyweight dependency. The Virtualization framework gives hardware-virtualized per-case sandboxes natively, with a layered-image story that mirrors what `scripts/build-agent-image.mjs` does for Docker. This is the premium native-macOS tier ON TOP of Docker cases, never a replacement (Docker remains the cross-platform story; the Linux prod box cannot use any of this).
+
+## 2. Platform reality (hard constraints)
+
+| Constraint                | Detail                                                                                                                                              |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Host OS                   | macOS 27 "Golden Gate" required for the new APIs (dev beta since 2026-06-08, public beta since 2026-07-13, GA expected fall 2026)                    |
+| Host hardware             | Apple Silicon only (macOS 27 dropped Intel). Testbed: the owner's dedicated MacBook (Section 8); the M4 Mac mini (macOS 26.4, runs the second Codeman install) stays on stable + untouched |
+| Guest provisioning        | `VZMacGuestProvisioningOptions` needs macOS 27 on BOTH host and guest. Linux guests provision via cloud-init instead                                 |
+| macOS guest concurrency   | **Hard kernel cap: 2 concurrent macOS VMs per host. MEASURED on 27 beta 4 (2026-07-29), not inferred**: the 3rd VM is refused instantly with `VZErrorDomain` code 6 while 39% of RAM is free, so more hardware does NOT raise it. Since macOS GUI guests are the headline use case, this is a real product capacity limit to schedule around and surface in the UI. Linux guests are uncapped (resource-bound only) |
+| Language                  | Virtualization framework is Swift/ObjC only; Node cannot call it. Requires a Swift helper binary (Key decision 2)                                    |
+| Entitlement               | Host process needs `com.apple.security.virtualization`. Fine for a locally built dev binary; distribution needs signing thought (Section 9)          |
+| Nested virtualization     | Linux-guest-only on M3+. A macOS 27 VM cannot dependably host its own guests, so the host-side APIs must be tested on bare-metal 27 (dual-boot)      |
+| CI                        | Cannot run in CI (needs beta macOS on Apple Silicon). Same answer as tmux/docker: no-op all VM IO under `VITEST`, unit-test the pure parts            |
+
+## 3. Goal and user stories
+
+Add "VM cases" to Codeman: a case can point at a per-case virtual machine on a macOS host, and any CLI backend runs inside it over the existing remote-SSH session machinery. A LOCATION OVERLAY on cases, exactly like remote-SSH and Docker cases, NEVER a sixth `SessionMode`.
+
+- As a Mac user, I link a case to a VM so an autonomous run executes behind a hardware virtualization boundary (stronger than Docker's shared kernel) while file viewing, transcripts, and hooks keep working.
+- Per-case VMs are instant and cheap: a shared provisioned base image plus a per-case overlay, not a full image copy per case.
+- Killing a session kills only its in-guest tmux; the VM stays up while sibling sessions remain; case delete tears the VM down.
+- I export a case's VM overlay as a portable artifact (mirror of `docker-exports/`), secrets excluded.
+- On a non-mac host, or a Mac without the helper, the feature is invisible: zero UI, zero probes, zero errors.
+
+Non-goals for the MVP: USB passthrough, custom Virtio channels (Phase 3 candidate), macOS-guest fleets (capped at 2 anyway), Kubernetes-style orchestration, Intel Macs.
+
+## 4. Architecture
+
+```
+Codeman (Node, unchanged session layer)
+  |  JSON over stdout (same pattern as shelling out to docker/tmux)
+  v
+codeman-vm  (Swift package: CLI + per-VM GUI runner app in the console session)
+  |  Virtualization / DiskImageKit / vmnet
+  v
+per-case VM (macOS or Linux)
+      |-- GUI mode: VZVirtualMachineView in a window  --> guest screen sharing --> browser (noVNC)
+      |-- shell:    SSH on vmnet IP                   --> existing remote-SSH tmux machinery
+      ^ VirtioFS: host case dir mounted at the SAME absolute path
+```
+
+Note the runner is a **GUI app in the console user's session**, not a detached daemon: a daemon-launched VM cannot render, which is fatal for macOS guests and for Linux desktop cases.
+
+### Key decision 1: location overlay, not a mode
+
+Identical reasoning to Docker/remote-SSH (see CLAUDE.md): the session layer, respawn, Ralph, recovery, and quick-start plumbing all stay untouched. `SessionMode` stays five-valued. State mirrors the Docker pair: `~/.codeman/vm-hosts.json` + `vm-cases.json`, new `src/vm-hosts.ts` with the storage + pure helpers split.
+
+### Key decision 2: Swift helper CLI (`codeman-vm`)
+
+The framework is Swift-only, so all VM work lives in a SwiftPM package (`packages/codeman-vm/`), a CLI with a stable JSON contract:
+
+- `create-base --guest linux|macos`: build the shared base image. Linux: boot an arm64 cloud image with EFI + cloud-init, install Node 22 + tmux + the four CLIs (same inventory as `docker/agent.Dockerfile`), seal as base ASIF. macOS: IPSW restore + `VZMacGuestProvisioningOptions` (agent user, SSH on), then **desktop-readiness baking**, which is mandatory for GUI guests: suppress the per-user first-login assistant (`com.apple.SetupAssistant` keys + the User Template), enable auto-login (`autoLoginUser` + `/etc/kcpassword`), disable screensaver/lock/display-sleep, and set a static wallpaper (animated "aerials" wallpaper is unusable over remote display). ⚠ Use RAW (not ASIF) for macOS guest disks until the beta's macOS-guest space-reclamation bug is fixed.
+- `create <case>`: DiskImageKit stacked image: shared read-only base + fresh per-case overlay. Near-instant, space-efficient.
+- `start <case>` / `stop` / `status` / `ip`: lifecycle + vmnet NAT; `ip` reports the guest SSH endpoint.
+- `export <case>` / `import`: flatten overlay + workspace tar + manifest, credentials excluded (mirror of docker-export).
+
+A VM dies with its owning process, so `start` spawns a DETACHED per-VM runner process (analog of the detached `scripts/self-update.sh` trick) rather than a monolithic daemon; `status` talks to it over a unix socket in the instance data dir (`dataPath()`, never a hardcoded `~/.codeman` path).
+
+### Key decision 3: multi-guest, and GUI is a first-class mode (REVISED 2026-07-29 by the repo owner)
+
+The subsystem supports both macOS and Linux guests, and a guest runs in one of two **display modes**:
+
+| | macOS guest | Linux guest |
+| --- | --- | --- |
+| **GUI mode** | **the point of the feature**; a real macOS desktop. Mandatory: nothing renders without an attached `VZVirtualMachineView` in an unlocked host session | supported (EFI + virtio-gpu framebuffer) for desktop Linux cases |
+| **Headless mode** | not offered: a macOS guest with no view renders nothing, so a "headless macOS desktop" is a contradiction. SSH-only macOS is possible but is not what this feature is for | supported and cheap; the natural mode for agent/CI work, driven over SSH |
+
+Consequences that flow from GUI being first-class:
+- VM processes are **GUI apps in the console user's session** (LaunchAgent / `launchctl asuser`), never daemons. A daemon-launched VM cannot render.
+- **The host is part of the product surface**: it must auto-login, never lock, never sleep, and keep a live WindowServer. Host lock == every VM's screen goes black, so the screen lock is effectively a global kill switch for every VM display on the machine. The product must own these host settings rather than treat them as user preference.
+- **FileVault conflicts with unattended GUI hosting** and the trade-off must be a deliberate choice: FileVault disables auto-login, so a full-disk-encrypted host needs a human at a keyboard (or a remote screen-sharing session) after every reboot before any VM can render. Options are (a) FileVault on, accept manual login per boot, (b) FileVault off on a dedicated VM host so it boots straight into a rendering session, or (c) FileVault on plus a remote-unlock runbook. Codeman should detect the state and tell the user which one they are in instead of silently serving black screens.
+- **Guests must be desktop-ready, not just booted**: auto-login, no screensaver/lock, and the per-user first-login assistant pre-suppressed at base-image time (`com.apple.SetupAssistant` keys, plus the User Template so later accounts inherit it). Otherwise the user connects to a login prompt or a setup wizard, which is exactly what happened during the first hands-on run.
+- **Capacity is capped for macOS**: at most 2 concurrent macOS VMs per host, confirmed by our own test on 27 beta 4 (3rd refused with `VZErrorDomain` 6 at 39% free RAM; it is a kernel quota, so bigger hardware does not help). Scheduling must queue or evict beyond 2, the UI must explain why, and the scheduler should tolerate the acknowledged slot-leak bug (a slot occupied with nothing running, host-reboot to clear). Linux guests are uncapped and bounded only by host resources, which is the lever for scaling case counts on one machine.
+- **Access is via the guest's own screen**, viewable in a browser through the noVNC chain (see `docs/vm-subsystem-apple-stack.md` §8), so no client-version or client-install requirements land on the user.
+
+Provisioning per guest type: `VZMacGuestProvisioningOptions` for macOS (needs 27-on-27, first-boot-only, and does NOT skip the per-user wizard), cloud-init NoCloud seed ISO for Linux (proven working).
+
+### Key decision 3b: the GUI VM host profile, and supervision that catches black screens
+
+GUI hosting only works if the host is configured for it and supervised. This profile was derived the hard way on the testbed (prototyped there 2026-07-30) and should be what `codeman-vm` installs and verifies:
+
+**Host profile** (the product should own these, not leave them to preference):
+1. **No login barrier.** Either FileVault off + auto-login (a dedicated VM host boots straight into a rendering session, fully unattended), or FileVault on and remote reboots done with `sudo fdesetup authrestart`, where the pre-boot unlock *is* the login so the machine returns already logged in with encryption intact. **`authrestart` is VERIFIED on the testbed (2026-07-30): the host rebooted remotely and came back with a live logged-in console session, FileVault still enabled, no password prompt** — this is the recommended pattern for an encrypted GUI VM host. Plain reboots on a FileVault host always need a human, so Codeman should detect that combination and warn instead of serving black screens.
+2. **Never lock**: lock policy off (needs the account password, so it is a setup step, not a scriptable one) plus `caffeinate -d -i -m -u` re-armed per session.
+3. **Never sleep**: `pmset -a sleep 0 displaysleep 0 disablesleep 1`; a physical display is NOT required (a lid-closed laptop renders fine, only an unlocked session matters). Note OS updates reset these.
+4. **Session-independent control plane**: run VPN/remote access as a system service, never a session app, and keep the access chain (forwards, VNC proxies, web endpoints) in LaunchDaemons so a session restart cannot sever operator access.
+
+**Supervision** must be a **root LaunchDaemon**, not a user LaunchAgent. This is the load-bearing detail: a user agent cannot launch a GUI app into the Aqua session, so its restart attempts fail *silently* (the child dies instantly, leaving an empty log while the supervisor cheerfully reports success). A root daemon can, via `launchctl asuser <uid> sudo -u <user> …`, and those launches persist. Prototyped and verified on the testbed 2026-07-30; a working supervisor runs on a short interval and:
+
+- Restarts the runner when the process is gone **or when its log shows `WindowServer event port death`**, which means it is permanently blind while still looking alive.
+- Defers restarts while the console is at the login window, and launches into whichever session actually exists (resolve the console user with `stat -f %Su /dev/console`, never a hardcoded one).
+- Re-points the guest port-forward whenever the guest's NAT lease changes, which happens on **every guest boot** under plain NAT. A vmnet DHCP reservation for a stable per-case IP is the better long-term answer.
+- **Re-applies host power settings**, because `pmset -a disablesleep 1` does NOT survive a reboot (caught on the supervisor's first run after a real reboot) and OS updates reset it too.
+- Re-arms the keep-awake helper, which dies with its session.
+- Ideally also samples the guest framebuffer for non-black content, since a black screen is the one symptom common to every failure mode here.
+
+`pgrep` alone is worthless for health: every failure mode in this session presented as a healthy process.
+
+### Key decision 4: sessions ride the existing remote-SSH machinery
+
+A provisioned guest is literally an SSH host on a vmnet IP. Session launch = the remote-SSH flow with the host swapped in: durable remote `tmux -L codeman-remote`, session names failing `SAFE_MUX_NAME_PATTERN` on purpose, EVERY ssh command line through `buildSshConnectionArgs()` (command-injection invariant), run flows through `POST /api/quick-start` (never `POST /api/sessions`, which stat-validates `workingDir` locally). What is genuinely new is only lifecycle (create/start/stop/export) and the vm-hosts/vm-cases overlay state.
+
+### Key decision 5: workspace via VirtioFS at the same absolute path
+
+Mirror the Docker bind-mount invariant: the case workspace is a real host directory shared into the guest via VirtioFS and mounted at the SAME absolute path. That keeps file-routes/watchers on real host bytes and makes the in-guest transcript projHash match the host. Without this, transcripts/attachments/file viewer all silently degrade.
+
+### Key decision 6: credentials seeded, hooks bridged
+
+- Credentials are SEEDED (read-only share, copied into the guest once at create), never shared read-write, and excluded from exports: byte-for-byte the Docker cases rule and rationale.
+- Hooks: on the loopback-only prod bind a guest cannot reach `127.0.0.1:3000`. Mirror `CODEMAN_DOCKER_BRIDGE_HOOKS` with a `CODEMAN_VM_BRIDGE_HOOKS` opt-in listener on the vmnet gateway IP; otherwise idle detection falls back to output-based, same as Docker.
+
+### Key decision 7: drift and teardown copy Docker semantics verbatim
+
+Config hash label on the VM (guest type, cpu/mem, share list); a drifted launch is REFUSED, never silently launched stale. One VM per case shared by all sessions; session kill = in-guest tmux kill only; case delete = stop + remove overlay; instance-scoped boot reaper for orphaned runner processes.
+
+## 5. Implementation phases
+
+**Phase 0, testbed (no repo code):** dedicated MacBook on the macOS 27 beta, remotely accessible over the tailnet (setup protocol in Section 8), Xcode 27 beta, then a throwaway Swift script proving the loop: create base -> overlay -> boot -> ssh in. This validates 80% of the design before any Codeman code.
+
+**Phase 1, `codeman-vm` helper:** SwiftPM package, the six subcommands above, JSON contract doc, detached runner + unix-socket status, Linux base image build. Deliverable is testable entirely without Codeman.
+
+**Phase 2, Codeman integration:** types (`VmHost`/`VmCase`/`SessionVm`), `src/vm-hosts.ts` (+ pure helpers: config hash, arg building, endpoint parsing), Zod schemas, `case-routes` link/unlink + listing, `quick-start` vm branch reusing the remote-SSH launch path, `Session` threading + recovery round-trip, `VITEST` no-op layer, unit tests. Feature-detect: darwin + arm64 + helper binary present, else invisible.
+
+**Phase 3, polish:** export/import UI, frontend Create Case "VM" tab + case-picker labels, SSE `vm:*` events, macOS-guest opt-in with cap surfaced, custom-Virtio input channel exploration, CLAUDE.md Key Pattern + `docs/vm-cases.md` + COM.
+
+## 6. Testing
+
+- Pure helpers unit-tested (ports pattern from `docker-hosts.ts`: 26 tests there, aim similar).
+- All helper-invoking IO no-ops under `VITEST` (the `IS_TEST_MODE` pattern in `tmux-manager.ts`).
+- End-to-end verification happens ON the beta MacBook, per the always-end-to-end rule: real base build, real per-case overlay boot, real quick-start into the guest, workspace round-trip through VirtioFS, session-delete keeps VM up, case-delete removes it.
+- CI never runs the real path; the static guards are type-level + unit-level only.
+
+## 7. Risks
+
+1. **Beta API churn**: everything here targets beta SDKs; symbol/behavior changes are likely before fall GA. Mitigation: Phase 0/1 are throwaway-tolerant; no Codeman-side commitment until the helper contract survives a beta cycle.
+2. **New artifact class**: Codeman ships pure TypeScript today; a Swift binary changes build/distribution (build-on-install via `xcrun swift build` on macs with Xcode CLT? prebuilt signed binary per release?). Needs an owner decision; local dev build is fine for the whole beta period.
+3. **Entitlement/signing**: `com.apple.security.virtualization` is trivial for local dev, real for distribution.
+4. **Adoption gating**: users need macOS 27 + Apple Silicon for months after GA. Docker cases remain the default recommendation; VM cases ship dark (feature-detected) with zero cost to everyone else.
+
+## 8. Beta testbed plan: dedicated MacBook (actionable now)
+
+Testbed is a dedicated MacBook the owner sacrifices to the beta (after a full backup). This supersedes the earlier dual-boot-the-Mini idea (git history has it): a dedicated machine means no OS-switching, no downtime for the Mini's live Codeman, and no FileVault pre-boot headaches.
+
+**Sequencing rule that makes it headless: configure ALL remote access on the CURRENT macOS first, THEN upgrade in place.** An in-place beta upgrade preserves Remote Login, Tailscale, user accounts, and auto-login, so there is no Setup Assistant and no post-install physical step. (A fresh install would boot into GUI-only Setup Assistant with no SSH, which on a headless box is a dead end.)
+
+Confirmed hardware (2026-07-28): MacBook, M3, 16 GB RAM, 256 GB disk with ~100 GB free. Verdict: green. M3 = eligible + nested-virt capable; 16 GB = host + 2-3 concurrent Linux guests (macOS guest = one at a time); 100 GB = fits with discipline: install Xcode 27 beta with the macOS platform only (skipping iOS/watchOS/tvOS simulators saves 15-20 GB), and defer any macOS guest base (~30 GB) to an external SSD or until actually needed. Linux guests + sparse ASIF overlays are the comfortable path.
+
+### Pre-upgrade checklist (owner, physical, once)
+
+1. Full backup (Time Machine or clone); the machine should be considered beta-only afterwards.
+2. Tailscale: install, sign into the tailnet, confirm it appears in `tailscale status` from another node.
+3. System Settings -> General -> Sharing: **Remote Login ON** (SSH) and **Screen Sharing ON** (for the rare GUI-only moments: Xcode license, Apple Account dialogs).
+4. **FileVault stays ON** (owner decision 2026-07-28, security over convenience). Consequences: auto-login is unavailable, but FileVault's pre-boot unlock doubles as login, so an unlocked boot still lands in a live GUI session; planned remote reboots go through `sudo fdesetup authrestart` (unlocks for exactly one restart); an UNPLANNED reboot (beta kernel panic, battery drain) parks the machine at the pre-boot screen, no SSH/Tailscale, until the password is typed physically. If the testbed goes silent, suspect this first. Keep it on AC so the battery absorbs power blips.
+5. Beta enrollment (manual): sign into the Apple Account in System Settings; System Settings -> General -> Software Update -> **Beta Updates** -> select the **macOS 27 Developer Beta** (preferred: framework fixes land weeks earlier than public beta; free since 2023 after accepting the agreement once at developer.apple.com; public-beta alternative: enroll at beta.apple.com). Then run the offered upgrade: plugged in, lid open, trusted network.
+6. Send over: tailnet name/IP, username, and a first-login password (key install + lockdown happens remotely right after).
+
+### Post-upgrade setup (remote, over the tailnet)
+
+1. Verify: `sw_vers` reports 27.x, SSH reachable.
+2. Server-ize the laptop: `sudo pmset -a sleep 0 disksleep 0 disablesleep 1` (lid-closed operation without an external display), `womp 1` (wake on network), `sudo systemsetup -setrestartpowerfailure on`. Keep on AC power.
+3. Install the controlling host's SSH key, then disable password auth.
+4. Xcode 27 beta install (the one step needing the owner's Apple Account sign-in once, doable via Screen Sharing from anywhere); `xcode-select`, license accept, verify `swift --version` + the 27 SDK (`xcrun --show-sdk-version`).
+5. Phase 0 prototype loop, all remote from here: Linux guest base image (no 27-on-27 provisioning dependency), DiskImageKit overlay, boot, vmnet NAT, ssh into the guest, run `claude --version` inside.
+6. Only after that loop works: start Phase 1 in `packages/codeman-vm/`.
+
+## 9. Open decisions (owner)
+
+1. Linux base distro/image for the default guest (proposal: Ubuntu 24.04 arm64 cloud image, matching the docker agent image's userland).
+2. Helper distribution for GA: build-on-install vs prebuilt signed binary vs "bring your own Xcode".
+3. Ship dark behind `CODEMAN_VM_CASES=1` for the first release, or feature-detect only?
+4. Export format parity with docker-exports (one manifest schema for both?).
+
+## References
+
+- Session 224: https://developer.apple.com/videos/play/wwdc2026/224/
+- Fleet-angle writeup: https://bitrise.io/blog/post/wwdc26-the-virtualization-framework-updates-that-matter-for-large-mac-fleets
+- Beta timeline: https://www.macworld.com/article/3189014/apple-july-2026-ios-ipados-macos-27-public-betas-tv-arcade-releases.html
+- Internal analogs: `docs/docker-cases-plan.md` (architecture template), `docs/remote-sessions.md` (session transport), `docs/architecture-invariants.md#docker-cases`

docs/vm-subsystem-apple-stack.md

@@ -0,0 +1,281 @@
+<!-- Reference doc for the VM subsystem (Codeman VM cases). Compiled 2026-07-29 from: Apple DocC JSON backend, macOS 27 beta 4 SDK on the testbed, a multi-source web research sweep, and hands-on prototyping on a MacBook Air M3 running macOS 27.0 beta (26A5388g). Companion to vm-cases-plan.md (the Codeman integration plan). -->
+
+# The VM Subsystem: Apple Virtualization Stack Reference (macOS 27 "Golden Gate")
+
+"VM subsystem" is the working name for Codeman's native-macOS VM isolation tier and everything under it. This document is the single place for what the Apple stack actually provides, what we have verified ourselves on the beta, and what is known-broken. The Codeman-side design lives in `docs/vm-cases-plan.md`.
+
+**Research method note:** Apple's HTML doc pages are JS-rendered and come back empty to fetchers. The working route is the DocC JSON backend: `https://developer.apple.com/tutorials/data/documentation/<path>.json` (page content) and `https://developer.apple.com/tutorials/data/index/<framework>` (full symbol tree with per-symbol `beta` flags). Everything below marked "Apple docs" was parsed from that backend directly.
+
+## 1. Component map and minimum OS versions
+
+| Component | What it is | Min host OS | Notes |
+| --- | --- | --- | --- |
+| Virtualization.framework core | VMs, EFI/Linux boot, virtio devices, VirtioFS | macOS 11-13 era | Unchanged basics; our prototype uses nothing newer than macOS 13 APIs except the DiskImageKit bridge |
+| **DiskImageKit** | ASIF + raw disk images, layered stacks | **macOS 27** | Swift-only, no ObjC headers. Section 2 |
+| **Guest provisioning** | First-boot account/SSH setup for macOS guests | **macOS 27 host AND guest** | Mac guests only as of beta 4. Section 3 |
+| vmnet topology/port-forward/DHCP APIs | Custom networks, port forwarding | **macOS 26** (NOT 27) | 27 adds exactly one fix: loopback port forwarding. Section 4 |
+| `VZVmnetNetworkDeviceAttachment` | In-process vmnet attach | macOS 26 | |
+| **`VZCustomVirtioDevice`** family | Custom paravirt devices | **macOS 27** | Linux guests only, custom guest driver required. Section 5 |
+| AccessoryAccess (USB passthrough) | USB claim + attach to VMs | macOS 27 | Requires paid-team provisioning profile, Dock app. Out of scope for Codeman. Section 6 |
+
+Corrections to the WWDC-session framing we started with: vmnet's topology family is a macOS 26 story (129 symbols, zero beta-flagged in 27); provisioning does NOT currently extend beyond macOS guests despite the generic-looking `VZGuestProvisioningOptions` base class; DiskImageKit has no attach/mount API at all (it is a file-format library that hands `DiskImage` objects to Virtualization, no `/dev/diskN`, no root needed, no entitlement documented).
+
+## 2. DiskImageKit (macOS 27, Swift-only)
+
+Public framework, `/System/Library/Frameworks/DiskImageKit.framework`. No ObjC headers; the API surface lives in the `.swiftinterface`. Verified present in the CLT 27 beta 4 SDK, and our prototype compiled against it with plain `swiftc` on the first attempt.
+
+### API surface (complete as of beta 4)
+
+```swift
+class DiskImage {
+  convenience init(creating: some DiskImage.CreationConfiguration) throws
+  convenience init(opening: some OpenConfigurationProtocol) throws
+  func appending(any DiskImage.CreationConfiguration & DiskImage.StackableLayer) throws -> any StackedImage
+  func appending(consuming DiskImage) throws -> any StackedImage   // reattach an existing layer; validates parentUUID
+  func truncate(blockCount: Int) throws                            // stacked: affects top layer; does NOT resize guest fs
+  var blockCount, blockSize, format, layerType, layerUUID, parentUUID, openMode, size, url
+}
+protocol StackedImage: DiskImage { var layers: [DiskImage] }
+struct OpenConfiguration { init(url:mode:); Mode = automatic | readOnly | readWrite }
+// CreationConfiguration statics: .asif(url:blockCount:blockSize:), .asifLayer(url:type:), .raw(url:blockCount:)
+// DiskImage.LayerType: .cache | .overlay | .overlay(blockCount:)
+// DiskImage.BlockSize: .bytes512 | .bytes4096
+// Errors: CorruptedImageError, IncompatibleStackingError(reason), InvalidBlockCountError, UnsupportedFormatError
+```
+
+Bridge into Virtualization is a new beta convenience init on the existing attachment class. Note there is no `readOnly:` parameter; read-only-ness comes from each layer's own `openMode`:
+
+```swift
+VZDiskImageStorageDeviceAttachment(diskImage: stack, cachingMode: .automatic, synchronizationMode: .full)
+```
+
+### Stacking rules (Apple docs, verbatim where quoted)
+
+- ASIF works standalone or stacked. "You can only use RAW images as standalone images or as **base** images in stacked configurations." Upper layers are always ASIF.
+- **One cache layer per stack**, any number of overlays conceptually, "shallow stacks perform better" (WWDC 224). No published max-depth guidance.
+- "Layers are processed from bottom (base) to top. The **topmost layer determines the stack's size and receives all writes**." `.overlay(blockCount:)` therefore also grows the virtual disk.
+- UUID chaining: appending sets the child's `parentUUID` to the parent's `layerUUID`. Raw bases have no UUID. "The layer UUID **changes if the layer is written to**", and reattaching a mismatched layer throws `IncompatibleStackingError`. This is the mechanism that makes a shared read-only base safe.
+- Base sharing across multiple VMs is the stated design intent ("can be shared across multiple VMs"), with the WWDC caveat that per-VM auxiliary files (EFI variable store, macOS auxiliary storage) must be duplicated per VM, never shared.
+- **There is no flatten/merge.** An overlay cannot be merged back into its base (confirmed by Howard Oakley's coverage plus an independent hands-on report). Export/move flows must ship the layer chain, or flatten inside a guest (dd to a fresh attached image).
+
+### Known issues and adoption
+
+- **ASIF space reclamation is broken for macOS guests on the beta** (deleted files never return space, survives reboots). Linux guests reclaim correctly on both raw and ASIF via `fstrim -av`. Single detailed field report, unrefuted. Since the VM subsystem targets macOS guests, the practical rule until this is fixed is: back macOS guest disks with RAW, and revisit ASIF stacking for macOS guests each beta (stacking still works, the disks just never shrink).
+- **Zero shipping adopters anywhere.** tart has a design issue with no activity; nobody has published working DiskImageKit code. Everything must be treated as field-untested (and our own testing bears that out, Section 8).
+- Framework binary grew every beta (588 → 598 across betas 1-4); expect churn until GA.
+- Release notes list no DiskImageKit known issues in any beta, which given the above says more about the notes than the framework.
+
+## 3. Guest provisioning (macOS guests only)
+
+```swift
+class VZGuestProvisioningOptions: NSObject { func validate() throws }   // "use one of its subclasses"
+class VZMacGuestProvisioningOptions: VZGuestProvisioningOptions {
+  var fullName, username, password: String
+  var logsInAutomatically: Bool
+  var enablesRemoteLogin: Bool   // SSH
+}
+// Wiring: VZMacOSVirtualMachineStartOptions.guestProvisioningOptions (Mac-typed)
+//         .setGuestProvisioning(_:) throws  (validating setter)
+```
+
+- **Requires macOS 27 on host AND guest.** Older guests **silently ignore** the options (no error).
+- **First boot after restore only.** Cannot reconfigure an already-provisioned VM; property changes after start are no-ops.
+- The base class is forward-looking scaffolding; its only subclass is Mac. A Linux/cloud-init analogue may come later; do not assume it lands in 27.0. For Linux guests, cloud-init NoCloud seed ISOs remain the provisioning path (proven working, Section 8).
+- Field-verified behavior (third-party hands-on, beta 3): provisioned account gets full admin + sudo; Setup Assistant fully skipped; SSH reachable ~48 s after first boot. **Race**: the account is created late in first boot (~T+54 s), after LaunchDaemons start (~T+33 s), so anything at daemon-level must wait for the account to exist.
+- Open Apple-acknowledged bug: provisioned users are invisible to `CSIdentityQueryExecute()` (FB23716201).
+- IPSW acquisition gotcha for automation: `VZMacOSRestoreImage.latestSupported` tracks the latest *release* (returned 26.5.2), not the installed beta; beta IPSWs must be fetched from the seed CDN explicitly.
+
+## 4. vmnet: a macOS 26 feature set, one macOS 27 fix
+
+Everything interesting shipped in macOS 26: `vmnet_network_create`, `vmnet_network_configuration_create`, `..._add_port_forwarding_rule`, `..._add_dhcp_reservation`, subnet/prefix/MTU/external-interface setters, NAT44/NAT66/DHCP/DNS-proxy/RA disables, plus serialization (`vmnet_network_copy_serialization` / `_create_with_serialization`) for handing networks across processes. `VZVmnetNetworkDeviceAttachment` is macOS 26.
+
+macOS 27's only change (beta 4 release notes, verbatim): "The vmnet port forwarding APIs now support port forwarding when communicating over loopback." That closes the old gap where the host could not reach its own forwarded ports via 127.0.0.1 (confirmed working by the original bug reporter). Directly relevant to Codeman's loopback-bound production server talking to per-case guests.
+
+Gotchas:
+- vmnet networks are **not persisted**; they die with the owning process. Persist settings yourself and recreate (or serialize across processes).
+- The `com.apple.vm.networking` entitlement is still restricted ("contact your Apple representative", though DTS says most requests are approved). The plain `VZNATNetworkDeviceAttachment` needs no special entitlement and is what our prototype uses.
+- Ecosystem signal: tart's maintainer is not adopting in-process vmnet (prefers their separate-process softnet), so field testing of these APIs is thin.
+
+## 5. VZCustomVirtioDevice (macOS 27, Linux guests only)
+
+14 new types (`VZCustomVirtioDevice(+Configuration/Delegate/Provider)`, `VZVirtioQueue(+Element)`, `VZVirtioFeatureSet`, shared-memory-region types, `VZGuestMemoryMapping`), wired via `VZVirtualMachineConfiguration.customVirtioDevices`. Mandatory for guest discovery: `deviceID`, `pciClassID`, `pciSubclassID`, `virtioQueueCount`. You must write the Linux guest driver (Virtio spec 1.3/1.4). Threading contract: the framework calls the device/delegate on a serial queue (`deviceQueue`, defaulting to the VM's queue). Zero public adopters. For the VM subsystem this is a Phase 3+ option for a low-latency host-guest channel; SSH over NAT is proven and sufficient for now.
+
+## 6. Signing and entitlements
+
+- **Core loop (VZ + DiskImageKit + provisioning): ad-hoc signing with only `com.apple.security.virtualization` suffices.** Verified by us on beta 4 (plain `codesign --entitlements ... -s -` on a `swiftc` binary) and independently by third parties on beta 3. DiskImageKit documents no entitlement at all.
+- **Over-entitling is the actual trap.** Adding `com.apple.application-identifier`/team-identifier keys without an embedded provisioning profile hangs the process before `main` (watchdog kill); shipping `com.apple.vm.networking` unauthorized gets AMFI SIGKILL at exec (exit 137, no crash report, even for `--version`). Keep the entitlements plist to exactly the one key.
+- **USB passthrough breaks the ad-hoc story**: `com.apple.developer.accessory-access.usb` is profile-restricted (any paid team, no ad-hoc), additionally requires `com.apple.security.device.usb`, and `AAUSBAccessoryManager` presents UI, so it wants a Dock app, not a headless CLI. Out of scope for Codeman.
+- No Xcode required for any of the above: the CLT beta (~500 MB via `softwareupdate`) carries the full macOS 27 SDK including DiskImageKit and compiles/signs everything.
+
+## 7. Ecosystem state (July 2026)
+
+- **tart is now `openai/tart`** (moved from cirruslabs, mid-2026) and **relicensed to FSL-1.1-ALv2** (no longer permissive). Provisioning support shipped in 2.33.0. Old cirruslabs URLs and license assumptions are stale.
+- VirtualBuddy shipped provisioning ("Skip Setup Assistant") in 2.2 betas; had to add account-detail validation and a workaround installer for the cross-version bug below.
+- lima is deliberately waiting for GA before touching macOS 27 APIs.
+- **Code-Hex/vz (Go bindings) is dormant** (no commits since Feb 2026, no macOS 27 APIs), so the entire Go ecosystem (podman-machine, colima) currently has no path to these APIs. Swift is the only realistic binding today, which validates the VM subsystem's Swift-helper design.
+- Useful pattern if ever supporting older SDKs: resolve new classes via `NSClassFromString` at runtime (no link-time dependency), fail gracefully when absent.
+- **Cross-version restore bug**: installing a macOS 27 guest from IPSW on a macOS 26 host fails at 77-78% (`VZErrorDomain 10007`); fixed in 26.6b3 + Xcode 27b4 era, with a nasty MobileDevice.pkg trap (installing it from Xcode 27 beta on a 26 host requires a full macOS reinstall to undo). Not relevant to our 27-host testbed, very relevant to anyone on a 26 host.
+
+## 8. Our empirical results (beta 4, 26A5388g, MacBook Air M3, 2026-07-29)
+
+Prototype tooling, all in `~/vm-lab/` on the testbed, compiled with CLT-only `swiftc` and ad-hoc signed with the single virtualization entitlement:
+
+| Tool | Purpose |
+| --- | --- |
+| `vzboot.swift` | Linux guest: EFI boot + virtio disk/net/entropy + NAT + optional cloud-init seed ISO + serial on stdio |
+| `vzstack.swift` | Same, but boots a DiskImageKit stack (read-only raw base + ASIF overlay) |
+| `vzmac.swift` | macOS guest: `install` (IPSW restore into a bundle) and `run` (boot, `--provision` for first-boot account/SSH) |
+| `vzmacgui.swift` | macOS guest in a real window via `VZVirtualMachineView` (required for the guest to render at all) |
+| `setup-seed.sh` | Builds a cloud-init NoCloud seed ISO with `hdiutil makehybrid` (volume label `cidata`) |
+| `vncproxy.py` | RFB proxy that advertises only security type 2, so version-skewed/browser clients can authenticate |
+| noVNC + `websockify` | Browser access; `websockify --web noVNC-<ver> 0.0.0.0:<port> 127.0.0.1:<proxy>` |
+| `vmwatchdog.sh` + `vmaccess.sh` | Supervision: root LaunchDaemon that restarts a blind/dead runner, re-points the forward, re-applies `pmset`, re-arms keep-awake; plus a keeper for the proxy/web endpoints |
+
+Host-side diagnostics written during this work (in the session scratchpad, not on the testbed): `vnclogin.py` (Apple DH auth + session open, distinguishes "credentials rejected" from "authorized but session refused"), `vncshot.py` (decodes the raw framebuffer to PNG and reports non-black pixel counts, plus optional synthetic wake input), `relay.py` (plain TCP relay used to bridge a tailnet peer to a LAN-only host), `sshpw.py` (pty-driven password SSH for the one-time key bootstrap into a freshly provisioned guest).
+
+### Proven working
+
+1. **Boot**: Debian 12 arm64 cloud images (nocloud and genericcloud variants) boot under `VZEFIBootLoader` + `VZGenericPlatformConfiguration`.
+2. **Networking**: `VZNATNetworkDeviceAttachment` gives the guest a `192.168.64.x` DHCP lease from the host's bootpd (leases visible in `/var/db/dhcpd_leases`, bridge is `bridge100`).
+3. **cloud-init provisioning**: NoCloud seed ISO (built with `hdiutil makehybrid -iso -joliet -default-volume-name cidata`) created a `codeman` user with SSH key + passwordless sudo on first boot; `ssh codeman@<lease-ip>` from the host works with key auth.
+4. **DiskImageKit stack mechanics**: opening a raw base `.readOnly`, appending an ASIF overlay (`ASIFCreationConfiguration.layer(url:type:.overlay)`), attaching via `init(diskImage:)`, and booting it. The overlay received ~44 MB of boot-time writes while the **base file's SHA-256 stayed bit-identical**, which is the write-isolation property the whole per-case design rests on.
+5. **Reattach**: reopening an existing overlay and `appending(consuming:)` onto the same base passes UUID validation.
+6. **macOS guest install (added later the same day)**: `VZMacOSInstaller` restore of the 27.0 IPSW (26A5388g, fetched from the seed CDN via appledb; same build as host) into a sparse 64 GiB raw disk + auxiliary storage: INSTALL-OK on the first attempt, ~25 minutes.
+7. **Headless guest provisioning WORKS**: `VZMacGuestProvisioningOptions` via `setGuestProvisioning` (username, password, `enablesRemoteLogin`, `logsInAutomatically=false`) produced, with zero GUI interaction: an account with full admin (groups include `80(admin)`, `com.apple.access_ssh`), Remote Login on from first boot, port 22 reachable ~140 s after first-boot start, hostname auto-derived from the account ("Codemans-Virtual-Machine"). SSH password auth is on by default, so the bootstrap path is: pty-driven password login once to install `authorized_keys`, key auth thereafter. Note the provisioned account's sudo is NOT passwordless (`echo <pass> | sudo -S ...`), and provisioning is first-boot-only (later boots take no options and just boot).
+8. **Slot-leak bug NOT reproduced on 26A5388g**: a guest-initiated `shutdown -h now` fired `guestDidStop` cleanly and an immediate relaunch started fine (SSH-ready again in ~75 s), so FB22967193 (VM slot leaked on guest-initiated shutdown, host reboot to recover) did not manifest after one cycle. Either fixed in beta 4 or needs more cycles to trigger.
+
+### Unstable / under investigation (beta-quality territory)
+
+Boot reliability degraded over a ~15-VM session on one host boot, ending with reproducible silent hangs (VM process alive, 0% CPU, no DHCP, no ARP, nothing on serial):
+
+- A genericcloud base that had been booted read-write once (cloud-init first boot) subsequently hung on every boot **with the seed ISO still attached**, while booting **without** the seed succeeded, then later runs failed in both configurations. The seed correlation is strong but was observed while host state was already suspect, so it needs a retest from a clean baseline.
+- The first stack-boot "success" that later wedged turned out (via DHCP lease timestamp arithmetic) never to have reached the network at all; its overlay growth was pre-network boot writes.
+- Working hypothesis, matching a class of acknowledged beta bugs (e.g. the VM-slot counter that leaks on guest-initiated shutdown, FB22967193, where only a host reboot recovers): accumulated hypervisor/vmnet state on the host degrades boots. Requires a host reboot + a disciplined retest matrix to confirm.
+
+### Display rendering: the single most important operational finding
+
+**A VZ macOS guest renders nothing unless a `VZVirtualMachineView` is attached AND the host session is actually drawing.** Verified byte-for-byte: the guest's own screen sharing serves an all-zero framebuffer (0 non-black bytes across 400 KB samples, with a sane pixel format: `rmax/gmax/bmax = 255`, shifts 16/8/0), in-guest `screencapture` fails with "could not create image from display", and no `IODisplayWrangler` shows up in the guest's `ioreg`. Three distinct states all produce black:
+
+1. **Headless** (VM run with no view attached).
+2. **View attached, host session locked.** The lock screen suspends drawing and the guest's virtual GPU produces no frames.
+3. **View attached, but the app lost its WindowServer connection** (see the incident below): black permanently until the app is restarted.
+
+**Consequence for the VM subsystem: rendering is a first-class requirement, not an optional extra (owner decision 2026-07-29).** The product serves GUI desktops: mandatory for macOS guests, optional-but-supported for Linux guests (which can also run headless over SSH). Any VM in GUI mode must be launched by an app that attaches a `VZVirtualMachineView`, from inside a host GUI session that is logged in and unlocked. That makes the following non-negotiable parts of the design, not workarounds:
+
+- VMs run as **GUI apps in the console user's session** (launched via a LaunchAgent or `launchctl asuser`), never as daemons.
+- The **host must auto-login and never lock or sleep**; a locked host is equivalent to a powered-off display for every VM on it.
+- The **guest must auto-login, never lock, and have its first-login assistant pre-suppressed**, or the "desktop" a user connects to is a password prompt or a setup wizard.
+- A VM app that loses its WindowServer connection is **permanently blind** and must be restarted; supervision has to detect that, not just check that the process is alive.
+- The **2-concurrent-macOS-VM cap** becomes a real capacity limit for the product, so it must be surfaced in the UI and tested (still untested worldwide as of this writing).
+
+### Incident 2026-07-29: `killall -HUP loginwindow` (never do this on a remote Mac)
+
+Applying a wallpaper change on the testbed with `killall -HUP loginwindow` restarted the host's login session. Three consequences:
+
+1. **The Mac dropped off the tailnet entirely.** Tailscale's App Store build is a GUI app living in the user session, so killing the session killed the VPN; remote access was gone until someone logged in. Recovery came from a second machine on the same LAN: it could still SSH in, and then relay ports back over the tailnet (a plain TCP relay on a tailnet-connected LAN peer is a good out-of-band path worth keeping ready).
+2. **The VM app lost its WindowServer connection** (`HIToolbox: received notification of WindowServer event port death`) while surviving as a process. Every later black screen traced to this, and nothing guest-side could fix it; only restarting the app restored rendering.
+3. The session's `caffeinate` died, so the host resumed auto-locking.
+
+Rule: on a remote Mac, never run session-level commands (`killall -HUP loginwindow`, `pkill -u <user>`, logout, fast user switching). `killall WallpaperAgent` alone is session-safe. Before any such command, enumerate what depends on that session: VPN, VM processes, port forwards, keep-awake helpers.
+
+### Keeping host and guest usable unattended
+
+- **Host**: `caffeinate -d -i -m -u` prevents display sleep but does NOT override the lock policy. "Require password after screen saver begins or display is turned off → Never" must be set in System Settings; it needs the account password, so a passwordless-sudo shell cannot script it, and turning it off does NOT dismiss a lock that is already engaged (one more unlock is always needed). `pmset -a disablesleep 1` keeps a lid-closed laptop awake but **does not survive a reboot**, and OS updates reset it too, so a supervisor should re-apply it rather than assume it sticks.
+- **Rebooting an encrypted host**: use `sudo fdesetup authrestart`. FileVault's pre-boot unlock doubles as the login, so the machine returns with a **live logged-in console session** and encryption intact, no password prompt, and supervision can then bring the VMs back by itself. Verified 2026-07-30. A plain `reboot` parks at the lock screen and blacks out every VM until a human logs in.
+- **Guest**: set `autoLoginUser` plus a valid `/etc/kcpassword` (XOR-obfuscated password file, key `7D 89 52 23 D2 BC DE A3`, payload zero-padded to a multiple of 12). `sysadminctl -autologin` fails with `SACSetAutoLoginPassword error:22` on provisioned accounts, and a fresh guest has no Python, so generate the bytes on the controlling host and copy them in. Then `pmset -a displaysleep 0 sleep 0 disablesleep 1`, `defaults -currentHost write com.apple.screensaver idleTime 0`, `defaults write com.apple.screensaver askForPassword 0`, and `caffeinate` inside the guest. ⚠ `autoLoginUser` was observed being wiped by failed `sysadminctl -autologin` attempts; verify it after each boot until stable.
+- **Wallpaper**: animated "aerials" wallpaper is brutal over VNC. The provider lives in `~/Library/Application Support/com.apple.wallpaper/Store/Index.plist` under several keys (`AllSpacesAndDisplays:Desktop`, `:Idle`, and `SystemDefault:*` which is what the login/lock screen uses). Switch each `Provider` to `com.apple.wallpaper.choice.solid-color` with PlistBuddy and restart `WallpaperAgent`. The login-window copy is cached and only refreshes on a later login cycle.
+
+### Remote GUI/SSH access to a guest (recipe, verified 2026-07-29)
+
+The guest lives on the host-private NAT bridge, so remote access is guest-service + host-forward:
+
+1. **In the macOS guest** (over ssh), use ONE mechanism, fully activated. The reliable form is Remote Management in a single kickstart call:
+   ```
+   sudo .../RemoteManagement/ARDAgent.app/Contents/Resources/kickstart \
+     -activate -configure -access -on \
+     -clientopts -setvnclegacy -vnclegacy yes -setvncpw -vncpw <8-char-pw> \
+     -allowAccessFor -allUsers -privs -all -restart -agent -menu
+   ```
+   ⚠ **Half-configured states authenticate but refuse the session.** Loading `com.apple.screensharing` while Remote Management is deactivated (or vice versa) produces an Apple-client error that names the wrong culprit: *"Screen Sharing is not permitted on <host>. Disable and re-enable Screen Sharing or Remote Management in System Settings"*. A raw-protocol client can still authenticate AND open a framebuffer in that state, so protocol-level tests pass while every Apple client fails. The remedy is exactly what the dialog says, done over ssh: `launchctl unload -w …screensharing.plist`, `kickstart -deactivate -configure -access -off`, `pkill screensharingd`, then the single activate call above.
+   Notes: `launchctl enable system/com.apple.screensharing` fails with "Could not find service" on this build; `load -w` is the plain-Screen-Sharing path if you deliberately want it instead of Remote Management. Apple clients negotiate `RSA-SRP` (auth type 33) and the guest logs `Authentication: SUCCEEDED :: User Name: … :: Type: RSA-SRP` on success, which is the definitive server-side confirmation.
+2. **On the host**: a gateway port-forward makes the guest's 5900 reachable from the whole tailnet without per-client tunnels: self-authorize the host's own key, then `ssh -N -g -L 0.0.0.0:5901:<guest-ip>:5900 <user>@localhost` (nohup'd).
+   ⚠⚠ **NEVER forward on host port 5900.** If the host has Screen Sharing enabled (our testbed does, from the pre-upgrade checklist), launchd already owns 5900 socket-activated. The `ssh -L` bind then fails with "Address already in use" **while the tunnel process keeps running**, so every symptom of success is present (process alive, port answers, real RFB banner) yet **every connection reaches the HOST's login window, not the guest**. This cost us an hour: guest credentials failed against the host's screensharingd, which reads exactly like broken guest auth, and we chased the (real, but irrelevant) provisioned-account identity bug. Diagnostics that would have caught it instantly: `sudo lsof -nP -iTCP:5900 -sTCP:LISTEN` showing `launchd` rather than `ssh`, or the guest's own logs showing NO auth attempts during a failed login. Always use a distinct host port and verify with `lsof` that the forward owns it.
+   ⚠ `-g` binds all interfaces, so the forward is also visible on the host's LAN; the VNC layer still requires the account or VNC password. ⚠ The forward pins the guest IP, which changes per boot under plain NAT; re-point it after a guest reboot (the proper fix is a vmnet DHCP reservation, macOS 26 API, once we move off plain `VZNATNetworkDeviceAttachment`).
+   Verified working: with the forward on 5901, both a provisioned account and a `sysadminctl`-created one authenticate successfully (RFB `SecurityResult` = 0) against the guest. The guest offers security types `[30, 33, 36, 2, 35]`, i.e. Apple DH/SRP **plus classic type 2**, so non-Apple VNC clients work with the legacy password once ARD's `-setvnclegacy` is set. (The host's screensharingd, by contrast, offered no type 2, which is itself a tell that you are talking to the wrong machine.)
+3. **SSH from any tailnet device**: `ssh -J <host-user>@<host> codeman@<guest-ip>` (jump through the host), after adding the connecting machine's key to the guest's `authorized_keys`.
+
+**Client-version incompatibility (macOS 27 servers vs older Screen Sharing clients)**: an older Mac's Screen Sharing client fails Apple's `RSA-SRP` handshake against macOS 27 servers, logging `Authentication: FAILED :: User Name: <user> :: Type: RSA-SRP` server-side, while a macOS 27 client authenticates against the same servers without issue. This was verified against BOTH a macOS 27 guest and a macOS 27 host with the operator's own account, so it is a client-side version skew, not configuration, and no server-side change fixes it. Same family as the documented "macOS 26 host cannot install a 27 guest" bug. Practical workaround: bypass Apple auth entirely with classic VNC auth (security type 2), which macOS offers only when Remote Management legacy VNC is enabled. Two ways to consume it: any third-party VNC client, or a browser via noVNC.
+
+**Browser-based access chain (zero client install, version-proof)**, all hosted on the Mac:
+```
+browser --HTTP/WS--> websockify (+ noVNC static files)
+                       --> type-2-only proxy   # rewrites the server's security-type list to [2]
+                         --> ssh -L forward     # loopback hop; see the Local Network note below
+                           --> guest:5900
+```
+Notes learned the hard way: (a) **never bind the forward on host port 5900** (see the launchd warning above); (b) a Python proxy cannot reach the guest subnet directly because macOS **Local Network privacy** denies headless CLI binaries, surfacing as `No route to host`, so point the proxy at a loopback `ssh -L` forward instead (Apple-signed `ssh` is unaffected); (c) noVNC needs `?resize=scale` or Scaling Mode → Local Scaling, otherwise a Retina host screen (2940x1912) is unusable in a browser window; (d) noVNC speaks security type 2 only, which is exactly why the proxy rewrite is needed.
+
+**Debugging technique that settled all of this**: a ~80-line Python RFB client (scratchpad `vnclogin.py`) that implements Apple DH auth (security type 30) and continues through `ClientInit`/`ServerInit`. It reports the server's `SecurityResult` plus the framebuffer size and desktop name, which separates "credentials rejected" from "authorized but session refused" without any GUI client. Pair it with `log stream --predicate 'process == "screensharingd"'` inside the guest, and drive a REAL Apple client headlessly from the host with `sudo launchctl asuser <uid> sudo -u <user> osascript -e 'tell application "Screen Sharing" to open location "vnc://user:pass@host:port"'`, verifying the result via `lsof -nP -iTCP -a -p <pid>` (an ESTABLISHED socket to the target) since `screencapture` fails on a lid-closed laptop ("could not create image from display"). Tailscale was never implicated: both the raw client and Apple's client work over the tailnet address once the guest service is fully activated.
+
+### Hard-won operational lessons (write these into any tooling)
+
+- **Silent serial is normal, not failure.** Debian's GRUB/kernel log to the graphics console; nothing attaches a getty to hvc0 by default. The reliable boot signal is the DHCP lease (or passive `tcpdump -i bridge100`), never the serial port and never a quick ping (BSD ping's first packet often dies to ARP latency; passive capture showed "dead" guests alive).
+- **DHCP lease entries carry truth**: `name=` shows the guest hostname, and the lease timestamps order events; stale entries linger, so compare timestamps before attributing a lease to a boot.
+- **Never boot a base image read-write.** Every RW boot mutates it (dhclient lease cache, journal, cloud-init state) and destroys experiment reproducibility, exactly why the production design only ever boots bases under overlays. Provision INTO the base once at base-build time, or provision per-case overlays with the seed, then detach the seed.
+- **A killed SSH client does not kill a remote `nohup`'d VM**, and the survivor holds the EFI variable store lock: "The EFI variable store is already in use" (`VZErrorDomain 50002`) means a zombie VM process, `pkill` it.
+- **EFI variable stores are per-VM state.** Fresh stores boot reliably; reuse across different VM instances is at minimum suspect on this beta (Apple's own guidance for cloned VMs is one store per VM). Cheap policy: one store per case, created with the overlay, deleted with it.
+- **Downloads from cloud.debian.org mirrors truncate silently**; always verify byte count against origin `Content-Length` and resume with `curl -C -`.
+- The remote host's default shell is zsh: `=` -prefixed words (`echo ===`) explode via zsh's `=cmd` expansion; keep separators zsh-safe in automation.
+
+### The 2-concurrent-macOS-VM cap: TESTED AND CONFIRMED on macOS 27 beta 4 (2026-07-29)
+
+We measured it, which as far as we can tell nobody had published for macOS 27. Method: `cp -c -R` the guest bundle (APFS clonefile, instant and **zero additional disk**), regenerate the machine identifier per clone (`VZMacMachineIdentifier()` written to `machine.id`; the hardware model is reused), then launch VMs until one is refused.
+
+Result: VM #1 (8 GB, GUI) and VM #2 (4 GB, headless) ran concurrently without complaint. VM #3 was refused **instantly** at `vm.start`:
+
+```
+VZErrorDomain Code=6 "The maximum supported number of active virtual machines has been reached."
+NSLocalizedFailure = "The number of virtual machines exceeds the limit."
+```
+
+**This is a licensing/kernel quota, not a resource limit**: the refusal came with **39% of system memory free** on a 16 GB host, and adding RAM or CPU cannot raise it. It matches the pre-27 behavior (`hv_apple_isa_vm_quota`), so nothing changed in 27 despite the framework's other additions. Linux guests are unaffected and are bounded only by host resources.
+
+Design consequences: macOS-guest capacity per host is **hard-capped at 2**, so a GUI-macOS-per-case product must schedule around it (queue, evict idle VMs, or scale across hosts) and surface it in the UI. Also relevant: the acknowledged slot-leak bug (a guest-initiated shutdown failing to release a slot, recoverable only by host reboot) is far more damaging under a cap of 2 than it sounds; we did not reproduce it on beta 4, but any scheduler should treat "slot appears used but nothing is running" as a real state.
+
+### Not yet tested
+- Cache layers (`LayerType.cache`), `.overlay(blockCount:)` disk growth, stack depth performance, VirtioFS + stack combination, `truncate`, ASIF disks for macOS guests (raw used so far; ASIF has the reclamation bug).
+- One more scripting lesson from this session: inner `ssh` calls inside a piped `sh -s` script MUST use `-n`, or they consume the remainder of the script from stdin and it silently never runs.
+
+### Session timeline (what was actually established, 2026-07-29)
+
+Linux path: base image download (with resume, mirrors truncate) → `vzboot` compiles against the beta SDK first try → EFI boot → NAT DHCP lease → cloud-init seed provisions a user with the host's SSH key → `ssh` into the guest works → DiskImageKit stack boots with an ASIF overlay taking all writes while the base stays SHA-identical. Later Linux boots became unreliable on an un-rebooted host (silent hangs, 0% CPU, no DHCP); a clean-baseline retest is still pending.
+
+macOS path: seed-CDN IPSW (matched to the host build) → `VZMacOSInstaller` restore, ~25 min, first try → first boot with `VZMacGuestProvisioningOptions` creates an admin account with Remote Login on, no interaction needed, SSH reachable ~140 s later → key bootstrap over a one-time password login → guest shutdown/relaunch clean (the slot-leak bug did not reproduce) → GUI access fought through a port collision, a client-version incompatibility, the rendering dependency, and a self-inflicted session kill, ending with a browser-based path plus a guest hardened to auto-login and never lock.
+
+**Lifecycle verified (stop → start), 2026-07-30**: an in-guest `shutdown -h now` fires `guestDidStop` and the runner app exits on its own; relaunching from the same bundle boots the guest in ~2 minutes straight into an auto-logged-in desktop, and the VM slot is released cleanly (an immediate restart works, so the slot-leak bug did not bite). Two operational notes: the guest takes a **new NAT lease on every boot**, so any port-forward must be re-pointed (or use a vmnet DHCP reservation), and a host reboot resets `pmset -a disablesleep`.
+
+⚠ **Provisioning does NOT skip the per-user first-login assistant.** `VZMacGuestProvisioningOptions` skips the initial Setup Assistant (account creation, region, Apple Account) so the machine is immediately reachable, but the first time anyone actually logs into a desktop, macOS still presents its per-user wizard (Apple Intelligence, Siri, privacy, appearance, Touch ID). The operator hit exactly this. For a GUI-first product this MUST be pre-suppressed during base-image creation by writing `com.apple.SetupAssistant` keys for every account that will log in, and into `/System/Library/User Template/English.lproj/Library/Preferences/` so accounts created later inherit it.
+
+⚠ **A partial key list is worse than none**, because the wizard simply shows the panes you missed and the operator has to click through them again after every fresh login (we hit this twice). The set that finally silenced macOS 27 beta 4: `DidSeeCloudSetup`, `DidSeeSiriSetup`, `DidSeePrivacy`, `DidSeeAppearanceSetup`, `DidSeeTouchIDSetup`, `DidSeeAvatarSetup`, `DidSeeScreenTime`, `DidSeeApplePaySetup`, `DidSeeSafariImport`, `DidSeeAccessibility`, **`DidSeeActivationLock`, `DidSeeAppStore`, `DidSeeLockdownMode`** (the three easy to miss), plus the Express-Settings flags **`SkipExpressSettingsUpdating`** and **`SkipFirstLoginOptimization`**, and the version markers `LastSeenCloudProductVersion` / `LastSeenBuddyBuildVersion` / `PreviousSystemVersion` / `PreviousBuildVersion` matching the guest build. Verify afterwards by reading the domain back and checking that no `DidSee*` key is still `0`. Note these keys change between macOS releases, so base-image creation should re-verify per OS version rather than trust a hardcoded list.
+
+## 9. Design implications for Codeman's VM subsystem
+
+0. **GUI is a first-class mode, and for macOS guests it is the whole point (owner decision, 2026-07-29).** The subsystem serves real desktops, not only headless SSH boxes. macOS guests are GUI-only in practice (nothing renders without an attached view). Linux guests are supported in BOTH modes: GUI when the case wants a desktop, headless-over-SSH when it wants a cheap agent sandbox. The costs of the GUI path are in §8 "Display rendering": VMs as GUI apps in a live session, a host that never locks, guests that auto-login with their first-login wizard pre-suppressed, and the macOS concurrency cap as a real capacity limit.
+1. **The macOS-specific liabilities are accepted costs, not reasons to avoid macOS guests**: provisioning is macOS-only and first-boot-only, ASIF space reclamation is broken for macOS guests on the beta (use RAW disks for macOS guests until fixed), and the 2-VM cap applies. Plan around each: RAW-backed macOS disks, provisioning baked into base-image creation, and capacity limits surfaced in the UI.
+2. **Base immutability is not just hygiene, it is load-bearing**: DiskImageKit's UUID invalidation plus our sha-stability proof make a read-only shared base per image-generation the core artifact. Bases are built once (seed attached), then only ever opened `.readOnly` under per-case overlays.
+3. **Seed ISOs are a base-build-time tool only.** Never attach a seed to a routine case boot (correlated with boot hangs on the beta, and semantically wrong anyway since cloud-init already ran).
+4. **Per-case files**: overlay ASIF + EFI variable store live and die together with the case.
+5. **Export = ship the layer chain** (base ref + overlay + manifest), not flatten; there is no flatten API. In-guest `dd` to a fresh image is the fallback for a true single-file export.
+6. **Health checking must be lease/API based**, not serial/ping based, and Codeman's `codeman-vm status` should read `/var/db/dhcpd_leases` (or use vmnet DHCP reservations for deterministic per-case IPs, a macOS 26 API).
+7. **Run `fstrim` periodically in Linux guests** (or mount with discard) so overlays stay sparse.
+8. **Entitlements plist stays minimal** (exactly `com.apple.security.virtualization`) to dodge the AMFI/watchdog traps.
+9. **Expect beta churn**: pin findings to build numbers (this doc: 26A5388g) and retest each beta; the framework binaries changed every beta so far.
+10. **A macOS guest is only "ready" when its desktop is ready**, which is a stricter bar than "the VM booted". Readiness means: VM app running with a live WindowServer connection, guest auto-logged-in (not at a login or lock screen), first-login assistant suppressed, and the guest's screen sharing serving a non-black framebuffer. Health checks should sample the framebuffer for non-black content, because every failure mode in this session (headless run, locked host, dead WindowServer, locked guest, setup wizard) presents as a perfectly healthy-looking process with a black or useless screen.
+10b. **Supervision must run as a root LaunchDaemon.** A user LaunchAgent cannot launch a GUI app into the Aqua session; its restarts fail silently (child dies instantly, empty log, supervisor reports success). Root + `launchctl asuser <uid> sudo -u <user> …` works and the launched process persists. This bit us on the first supervisor implementation and is easy to repeat.
+
+11. **Remote-access plumbing belongs in the helper CLI, not in ad-hoc shell**: a `codeman-vm` implementation should own port selection (never 5900), forward lifecycle across guest IP changes (or better, vmnet DHCP reservations for stable per-case IPs), and a documented browser path, because every failure in this session came from hand-rolled plumbing rather than from the Virtualization APIs themselves.
+12. **Never let control-plane connectivity depend on a GUI session** on a remote Mac host: prefer a Tailscale system service over the App Store app, and keep a LAN-adjacent peer able to relay as an out-of-band recovery path.
+
+## Sources
+
+Apple DocC JSON backend (diskimagekit, virtualization, vmnet trees; macOS 27 release notes) | WWDC26 session 224 https://developer.apple.com/videos/play/wwdc2026/224/ | eclecticlight.co ASIF/virtualization coverage | developer.apple.com/forums threads 839343 (CSIdentity bug), 830118 (cross-version restore), 830119 (VM-slot leak), 830383 (VM cap), 834822 + 831902 (USB entitlements), 822658 (vmnet loopback) | openai/tart issues 1261/1263/1268/1269/1285 | Spooky-Labs provisioning design doc | VirtualBuddy 2.2 release notes | lima-vm discussions | our own test transcripts on the testbed (`~/vm-lab/*.log`, this repo's session)

docs/web-tabs.md

@@ -1,7 +1,7 @@
 # Web Tabs (dashboards as Codeman tabs)
 
 Open any dashboard you run, Grafana, Uptime Kuma, Portainer, a status page on port
-4000, as a tab beside your Claude/Codex/Gemini sessions. Codeman becomes one mission
+4000, as a tab beside your Claude/Codex/Antigravity sessions. Codeman becomes one mission
 control instead of Codeman plus a pile of browser tabs.
 
 ## Using it
@@ -46,7 +46,42 @@ Codeman, including a phone that is not on the tailnet.
 
 `direct` mode (a plain cross-origin iframe) still exists and is cheaper, but it only
 works for an HTTPS dashboard that permits framing. The **Test** button probes from
-the server and tells you which mode applies.
+the server and tells you which mode applies. Note what Test actually verifies:
+**server-to-upstream reachability, nothing else**. It does not exercise the browser
+sandbox, cookies, CORS, CSP, or any reverse proxy sitting in front of Codeman, so a
+passing Test does not guarantee the embedded page will render (see the
+cookie-authenticated reverse proxy caveat below).
+
+## Links to `localhost` from another device
+
+An agent prints `http://localhost:5173/` (a dev server, a preview, a report it just
+served) and you tap it on your phone. That address only exists on the Codeman box, so
+the phone's browser can never load it — but the web-tab proxy fetches from the server,
+where it works.
+
+So a **loopback** link (`localhost`, `127.0.0.0/8`, `0.0.0.0`, `::1`) clicked
+in the terminal or in the Response Viewer opens as a **proxied web tab** whenever the
+Codeman page itself is not on that box. A saved proxied dashboard on the same origin is
+reused (one tab per dev server, with the link's own path opened inside it, and one tab
+per dev server rather than per host spelling, so `localhost:5173` and `127.0.0.1:5173`
+share it); otherwise one is saved under its `host:port` so it is in the Run dropdown
+next time, and a toast tells you it was saved. Sandboxed by default, like any other web
+tab.
+
+⚠️ **`*.localhost` is deliberately not auto-routed**, even though a browser treats it as
+loopback. Every other name in that list is an address literal that can only mean this
+box; a `*.localhost` DNS name is not one, and on a resolver with a search domain
+configured `evil.localhost` can be retried as `evil.localhost.<search domain>`, which
+someone else can control. Since the links come from agent output, one tap would then
+make Codeman fetch an agent-chosen origin server-side and save it. If you really run
+`api.localhost` dev hosts, add that dashboard by hand: doing so is an explicit action,
+which is the difference that matters here. A **trusted** (non-sandboxed) dashboard is
+likewise never auto-reused by a tapped link, for the same reason.
+
+Only loopback is routed this way. A LAN or tailnet address (`192.168.…`, `100.…`,
+`box.ts.net`) may well be reachable from the device — a VPN, the same Wi-Fi — and a
+direct open is the cheaper, richer path, so those links still open in a new browser tab.
+On the box itself (a browser on `localhost`) every link opens directly.
 
 ## The sandbox, and when to turn it off
 
@@ -66,6 +101,17 @@ Even in trusted mode, Codeman never forwards its own credentials upstream: the
 `Authorization` header and the `codeman_session` cookie are stripped on the way out,
 so `CODEMAN_PASSWORD` cannot leak into a dashboard.
 
+⚠️ **Sandboxed tabs may not work when Codeman itself is behind a
+cookie-authenticated reverse proxy** (Cloudflare Access, Authelia, oauth2-proxy and
+similar). The sandboxed frame is opaque-origin, so its stylesheet, script, and API
+requests do not carry the proxy's authentication cookie; the proxy redirects them to
+the login provider, where CORS/CSP kills them, and the embedded app renders
+unstyled or broken while the Codeman page around it works fine. Trusted mode
+(**Open sandboxed** off) keeps a real origin and the cookie, so it works. The
+**Test** button cannot catch this: it checks that the Codeman *server* can reach the
+upstream, not that a sandboxed *browser* frame can load assets through the public
+authentication layer.
+
 ## How the proxy authenticates
 
 A sandboxed iframe is opaque-origin, so every request it makes is cross-site: the
@@ -113,6 +159,24 @@ layers cooperate so a dashboard talking to its own backend just works:
    using its `Referer` to identify the dashboard. This only fires for a request
    that already missed every Codeman route, and never for one that resolves to a
    real route, which is what keeps it from being an authentication bypass.
+5. The same script **masks the proxy prefix off the page's own URL** before any
+   of the page's code runs (`history.replaceState` to the path the page would see
+   on its own origin). A single-page app routes on `location.pathname` at boot,
+   and `/webview/<cap>/` is a path no app has a route for: without this, a React
+   Router / Vue Router / Next dev server painted its HTML and CSS and then replaced
+   them with its own "page not found" the moment its script ran. The page only
+   *reads* the masked path; every URL it emits still goes through the layers above.
+6. A navigation the page starts **itself** after that — `location.reload()` (a dev
+   server's full-reload HMR), a root-absolute `location.href = '/login'` — now
+   targets Codeman's root with no capability anywhere on it. Codeman recognises
+   that request by shape (a top-level `<iframe>` navigation asking for HTML, for a
+   path it does not serve) and answers a static page that does nothing but tell
+   the owning tab which path was lost; the tab remounts the frame inside the
+   prefix at that path. It never counts as a failed login, so a dev server that
+   reloads on every save cannot rate-limit its user out of Codeman. The landing
+   page is the one served path that gets the same answer: it masks to exactly
+   `/`, and a reload there is admitted as long as the request carries no Codeman
+   credentials, which a sandboxed frame never does.
 
 On top of that, the proxy answers those requests with CORS headers. That sounds
 wrong for same-host requests, but a sandboxed iframe has an *opaque* origin, so the
@@ -126,10 +190,22 @@ then every API call fails, which looks like the dashboard being broken.
   EventSource, normal markup, the DOM sinks a page uses to build markup at runtime,
   and `url()` inside stylesheets. Something that constructs requests by an unusual
   route can still slip through. Symptom: the page renders but a panel stays empty.
-- **Root-absolute `location` navigation.** A dashboard that navigates itself with
-  `location.href = '/login'` escapes the prefix, because `Location.href` is
-  unforgeable and cannot be patched the way the other sinks are. A relative
-  `location.href = 'login'` is fine (`<base>` covers it).
+- **A root-absolute `url()` inside an inline `<style>` is not rescued.** Masking the
+  page's URL (layer 5) trades away the `Referer` safety net of layer 4 for
+  requests the shim cannot see, and only HTML is rewritten server-side. An
+  external stylesheet is fine: a `url()` it references is fetched with the
+  stylesheet's own URL as `Referer`, which is still inside the prefix. A
+  root-absolute `url(/img.png)` written directly into a `<style>` block in the
+  document has the masked document as its `Referer`, so it 404s where the
+  fallback used to rescue it. Symptom: one background image missing while
+  everything else renders. Narrow, and a `url()` the page sets from script is
+  still covered by layer 3.
+- **Root-absolute `location` navigation is recovered, not prevented.** `Location`
+  is unforgeable, so `location.href = '/login'` or `location.reload()` really does
+  leave the prefix; the frame comes back through the recovery hop in layer 6 above,
+  which needs a browser that sends `Sec-Fetch-Dest` (every current one; iOS Safari
+  since 16.4). Older browsers show Codeman's 404 in the frame; the tab's **Reload**
+  button puts it back.
 - **Cross-origin redirects are not followed.** If a dashboard bounces to a different
   host (an external SSO provider, say), the proxy hands the redirect back unchanged
   rather than relaying it, because relaying would make this an open proxy. Use
@@ -137,10 +213,30 @@ then every API call fails, which looks like the dashboard being broken.
 - **Login-protected dashboards need trusted mode**, since a sandboxed frame has no
   cookie jar. A server-side per-dashboard cookie jar would lift this and is the
   natural next step if it becomes annoying.
-- **Not a security boundary.** The proxy reaches whatever the Codeman server can
-  reach. That is not an escalation for someone who already commands
-  `--dangerously-skip-permissions` agents, but in multi-user mode it does mean a
-  non-admin user's dashboard is fetched from the server's network position.
+- **Cookie-authenticated reverse proxies in front of Codeman break sandboxed tabs**
+  (#238). The sandboxed frame's requests carry no auth cookie, so the proxy bounces
+  them to its login provider and the app loads broken while Test reports reachable.
+  Use trusted mode behind Cloudflare Access and friends; see the warning above.
+- **Slow endpoints and the upstream timeout** (#237). The proxy waits
+  `CODEMAN_WEBVIEW_TIMEOUT_MS` (default 300s) for the upstream's response *headers*,
+  then streams the body without any time bound; a header timeout is logged
+  server-side and answered as a 502 that names the limit. WebSocket handshakes use
+  the separate `CODEMAN_WEBVIEW_WS_HANDSHAKE_TIMEOUT_MS` (default 30s).
+- **Not a security boundary, with one carve-out.** The proxy reaches whatever the
+  Codeman server can reach (a `localhost` dashboard is the point), so it is not an
+  escalation for someone who already commands `--dangerously-skip-permissions`
+  agents, but in multi-user mode it does mean a non-admin user's dashboard is
+  fetched from the server's network position. The carve-out: link-local and
+  cloud-metadata addresses (`169.254.0.0/16`, `fe80::/10`, `fd00:ec2::254`,
+  Azure's `168.63.129.16`, Alibaba's `100.100.100.200`, the
+  `metadata.google.internal` alias) are refused at save time AND at connect
+  time, judged on the address a name actually resolves to. Nothing anyone embeds
+  as a dashboard lives there; an instance's IAM credentials do.
+- **The proxy URL is a bearer credential.** `/webview/<cap>/...` needs no cookie,
+  so treat it like a password. It is revoked when you log out, when an admin logs
+  you out, and when your account is deleted, and it expires after 12 hours
+  without use. Proxied responses carry `Referrer-Policy: same-origin`, so a
+  dashboard that links to third-party sites does not hand them the URL.
 
 ## Where the code lives
 

docs/wiki/Agent-CLIs.md

@@ -0,0 +1,288 @@
+# Agent CLIs
+
+Codeman drives ten run modes: nine agent CLIs plus a plain shell. This page covers picking
+one, setting it up, and the differences that actually change how you work.
+
+## The ten modes
+
+| Mode                 | CLI                          | Get it                                                                 |
+| -------------------- | ---------------------------- | ---------------------------------------------------------------------- |
+| **Claude Code**      | `claude`                     | [docs.anthropic.com](https://docs.anthropic.com/en/docs/claude-code)   |
+| **OpenCode**         | `opencode`                   | [opencode.ai](https://opencode.ai)                                     |
+| **Codex**            | `codex`                      | [developers.openai.com/codex/cli](https://developers.openai.com/codex/cli) |
+| **Gemini**           | `gemini`                     | [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) |
+| **Antigravity**      | `agy`                        | [antigravity.google](https://antigravity.google)                       |
+| **Pi**               | `pi`                         | [pi.dev](https://pi.dev)                                               |
+| **Grok Build**       | `grok`                       | [github.com/xai-org/grok-build](https://github.com/xai-org/grok-build) |
+| **DeepSeek Harness** | `dsh`                        | [github.com/deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) |
+| **OMP**              | `omp`                        | [github.com/can1357/oh-my-pi](https://github.com/can1357/oh-my-pi)     |
+| **Terminal / Shell** | your `$SHELL`                | Already installed.                                                     |
+
+Any combination works, including all of them. The run mode is chosen per session from the
+arrow beside the **Run** button, so one case can have a Claude session and a Codex session
+open side by side.
+
+## Codeman does not manage your logins
+
+Install each CLI yourself and log it in once by hand. Codeman never collects, stores, or
+refreshes your CLI credentials. It launches the binary and attaches to the result.
+
+The one place credentials are touched is [Docker Cases](Docker-Cases), where host
+credentials are copied into a container read-only at launch so you do not have to log in
+again inside it. Even there, the container keeps its own copies and never writes back to
+your host credential stores.
+
+## Making a CLI visible to Codeman
+
+Codeman resolves each binary from the environment the **server** runs in, which is not
+necessarily the shell you tested in.
+
+```bash
+codeman doctor          # what Codeman can actually see
+codeman doctor --json
+```
+
+If a CLI is installed but a Run button for it never appears:
+
+1. Check `which <cli>` in a plain login shell, not just your interactive one.
+2. If Codeman runs as a service, remember that launchd hands a job
+   `/usr/bin:/bin:/usr/sbin:/sbin`. `codeman service install` bakes your PATH into the unit
+   precisely to avoid this; a hand-written plist or unit will not.
+3. Restart the server after installing a new CLI.
+
+`pi`, `grok`, `omp` and `dsh` are additionally identity-probed rather than trusted by name:
+`pi` and `omp` are generic enough that something else on your PATH may answer to them,
+`grok` has npm squatters, and Debian ships an unrelated `dsh` (dancer's shell). Each has a
+status endpoint (`/api/grok/status`, `/api/deepseek/status`, `/api/omp/status`) that reports
+the path and version that actually resolved, so a misresolution is visible rather than
+presenting as "the mode just does not work".
+
+## Claude is the reference mode
+
+A number of Codeman features exist only for Claude sessions. This is structural, not a
+backlog: they depend on Claude Code's hook system, or on parsing Claude's specific terminal
+output. The other CLIs expose no equivalent.
+
+| Feature                                          | Claude | Other CLIs                                          |
+| ------------------------------------------------ | ------ | --------------------------------------------------- |
+| Sessions, tabs, scrollback, exactly-once input    | Yes    | Yes                                                  |
+| Respawn cycling and unattended runs               | Yes    | Yes                                                  |
+| Cron jobs                                         | Yes    | Yes                                                  |
+| Docker cases, remote SSH cases                    | Yes    | Yes                                                  |
+| Precise idle detection                            | Yes    | Codex: same screen check, via its own prompt and working line. DeepSeek: reports its state itself. Others: output stabilization, coarser |
+| Auto-resume when a usage limit resets             | Yes    | No                                                   |
+| Plan usage chip                                   | Yes    | No                                                   |
+| Approvals Inbox                                   | Yes    | DeepSeek yes; others no                              |
+| Read My Mind                                      | Yes    | No                                                   |
+| Ralph loop and its task tracker                   | Yes    | No                                                   |
+| Subagent and team windows                         | Yes    | No                                                   |
+| Model, effort, and ultracode controls             | Yes    | No                                                   |
+| `stop` and `blocked` wait signals                 | Yes    | DeepSeek yes; elsewhere 400 if you ask for them explicitly |
+| The bundled agent skill                           | Yes    | No                                                   |
+
+Everything that makes a session a session works everywhere. What is Claude-only is mostly
+the machinery that needs to know *what* the agent is doing rather than *that* it is doing
+something.
+
+## Per-CLI notes
+
+### Claude Code
+
+The defaults you will care about, all under **App Settings**:
+
+- **Model** (Models section). Written into the case's `.claude/settings.local.json` as a
+  soft default, so `/model` still works mid-session. The 1M-context Opus variant is a
+  switch on the model card rather than a separate model.
+- **Effort** (`low` through `max`) or **ultracode** for dynamic multi-agent workflows. Also
+  a soft default: `/effort` overrides it any time. Effort is deliberately not passed as an
+  environment variable, because that would hard-lock it and block in-session switching.
+- **Startup permission mode** (Agents & CLIs section). The default is
+  `--dangerously-skip-permissions`, which is why the security model matters. You can switch
+  new sessions to Anthropic's classifier-guarded `auto` mode, normal prompting, or an
+  explicit allowed-tools list.
+
+**Separate Claude accounts per session.** Set `CLAUDE_CONFIG_DIR` in a session's environment
+overrides to point it at a different Claude config directory, which is how you run one
+session on a client's subscription and another on your own. One caveat: a relocated config
+directory writes transcripts outside `~/.claude/projects`, which blinds the response viewer,
+subagent windows, ultracode panel, and Read My Mind for that session. Symlink `projects`
+back into the shared tree to keep them working:
+
+```bash
+ln -s ~/.claude/projects <configDir>/projects
+```
+
+### OpenCode
+
+Renders its own TUI, so Codeman treats readiness as output stabilization rather than
+watching for a prompt marker. Requires tmux, with no direct-PTY fallback, because its
+environment is injected through socket-scoped `tmux setenv` rather than the command line.
+
+Integration detail: [`docs/opencode-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/opencode-integration.md).
+
+### Codex
+
+Two behaviours that are deliberate and worth knowing:
+
+- **Predictive echo instead of buffered echo.** Codex's composer reacts to every keystroke,
+  a `/` opens a live-filtering picker, arrows edit server-side state. Buffering keystrokes
+  until Enter starved it, so Codex paints each keystroke at the predicted cell while the
+  bytes on the wire stay byte-identical to what you typed.
+- **The wheel is not forwarded** into its transcript. Codex ignores the mouse reports
+  Codeman would send, so forwarding produced a dead wheel. Scrolling in a Codex session is
+  local scrollback.
+- **Work detection is Codex's own.** Codex declares its `›` composer glyph and its
+  `esc to interrupt` working line, so it gets the same screen-checked idle detection Claude
+  does; before 1.26.1 every Codex session reported idle for its whole life. Codex
+  conversations also appear in Past Sessions and can be resumed, and on phones the keyboard
+  bar grows `⇧←` / `⇧→` for Codex's queued-message editing and prompt stack.
+
+### Gemini
+
+Enterprise only, since Google's June 2026 consumer cutover. Its environment allowlist
+includes the broad `GOOGLE_*` namespace, deliberately, because Vertex AI authentication
+needs `GOOGLE_CLOUD_PROJECT`, `GOOGLE_APPLICATION_CREDENTIALS`, and
+`GOOGLE_GENAI_USE_VERTEXAI`. That is the loosest allowlist entry in Codeman and it affects
+only the CLI you spawned yourself.
+
+### Antigravity
+
+Google's successor to the consumer Gemini CLI, invoked as `agy`. It keeps all of its state
+in `~/.gemini/antigravity-cli/`, so the credential handling that applies to Gemini applies
+to it as well.
+
+### Pi
+
+Pi needs the opposite instincts from every other CLI here.
+
+- **It has no permission prompts and no sandbox.** There is no bypass flag to send, and
+  Codeman does not invent one.
+- **Its privileged setting is project trust**, a three-way `--approve` / `--no-approve` /
+  unset. Approving trust makes Pi **execute repo-local `.pi/extensions` TypeScript**, so
+  point it at a repository you trust. In multi-user mode, a user without an explicit grant
+  gets `--no-approve` even when no configuration exists.
+- **Authentication is `/login` inside the session**, or the server process's own
+  environment. Pi's roughly 34 provider keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+  `HF_TOKEN`, and so on) share no common prefix, and the environment allowlist is global
+  rather than per mode, so admitting them for Pi would widen the allowlist for every mode at
+  once. They stay out.
+
+Guide: [`docs/pi-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/pi-integration.md).
+
+### Grok Build
+
+xAI's `grok`, installed with `curl -fsSL https://x.ai/cli/install.sh | bash` into
+`~/.grok/bin`. Codex-shaped on permissions and OpenCode-shaped on rendering:
+
+- **Its bypass switch is `--always-approve`**, Grok's own `bypassPermissions` mode, and the
+  Run button sends it the way it sends Codex's. In multi-user mode a user without a grant
+  has it stripped.
+- **Authentication is Grok's own**: browser OAuth on first run (a device-code screen inside
+  a Codeman pane), `grok login --device-auth` for headless hosts, or `XAI_API_KEY` as a
+  per-session environment override.
+- It renders a full-screen TUI, so scrolling is local scrollback.
+
+Guide: [`docs/grok-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/grok-integration.md).
+
+### DeepSeek Harness
+
+The mode wired least like the others, for two reasons worth knowing before you use it.
+
+**`dsh` is a launcher, not an agent.** It boots a *profile*, and the three DeepSeek ships
+(`web`, `headless`, `base`) cannot drive a terminal pane. So "installed" and "runnable" are
+different questions: the Run menu offers **DeepSeek** only once a pane-capable profile
+exists, and until then shows **DeepSeek — add a terminal profile…**, which installs the
+community `dsh-tui` with one click (`pnpm` must be on PATH, because the launcher spawns it
+directly).
+
+**Permissions are an environment variable, not a flag.** The harness has no
+skip-permissions switch. `DSH_PERMISSION_MODE` (`read-only`, `workspace-write`,
+`danger-full-access`) is the whole control, and it is the one setting Codeman deliberately
+carries as an environment variable, because the harness reads it as a soft boot-time
+default. In multi-user mode a user without a grant is clamped to `workspace-write`.
+
+The reward for the odd wiring: **DeepSeek is the one non-Claude mode with real signals.**
+Its terminal front door reports idle, working and blocked to Codeman, so a DeepSeek
+session gets precise idle detection, the `stop` and `blocked` wait signals, and Approvals
+Inbox items. Answers are read from the harness's own transcript on disk rather than
+scraped off the pane. The model is not a session setting; it is part of the profile.
+
+Guide: [`docs/deepseek-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/deepseek-integration.md).
+
+### OMP
+
+Oh My Pi, installed with `curl -fsSL https://omp.sh/install | sh` into `~/.local/bin`.
+OMP owns its auth, provider routing and approval mode entirely in `~/.omp`: there is no
+Codeman-side login, key field, or bypass switch. Run `omp` once outside Codeman to finish
+its own onboarding, and every session started through Codeman inherits that config. Its
+documented default approval mode is `yolo`, so an OMP pane auto-approves tool use with no
+flag from Codeman; change that in OMP's own config, not here.
+
+OMP conversations appear in Past Sessions and can be resumed, and a respawn continues the
+same conversation with `--continue`.
+
+Guide: [`docs/omp-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/omp-integration.md).
+
+### Terminal / Shell
+
+A plain shell in a tmux session. No agent, no hooks, no idle detection.
+
+On phones a shell session automatically swaps the keyboard accessory bar for terminal
+controls: Ctrl, Esc, Tab, arrows, paste. **Ctrl is a one-shot modifier**: tap it, then tap a
+letter, and the control byte is sent. It disarms on use, on a second tap, on any other
+accessory key, on a session switch, and when the keyboard closes. Details in
+[Mobile Guide](Mobile-Guide).
+
+## Environment overrides
+
+Per-session environment variables are set when creating a session and persist across
+respawns. Which variables are accepted depends on the mode:
+
+| Mode        | Allowed prefixes                  |
+| ----------- | --------------------------------- |
+| Claude      | `CLAUDE_CODE_*`, plus the exact key `CLAUDE_CONFIG_DIR` |
+| OpenCode    | `OPENCODE_*`                      |
+| Codex       | `CODEX_*`                         |
+| Gemini      | `GEMINI_*`, `GOOGLE_*`            |
+| Antigravity | `ANTIGRAVITY_*`                   |
+| Pi          | `PI_*`                            |
+| Grok        | `GROK_*`, `XAI_*`                 |
+| DeepSeek    | `DSH_*`, `DEEPSEEK_*`             |
+| OMP         | `OMP_*`                           |
+
+Anything outside the allowlist is rejected at the schema. This is intentional: the allowlist
+is one global list, so widening it for one CLI widens it for all of them. In multi-user mode
+the keys that could redirect a CLI's traffic or move its config home (`DSH_PERMISSION_MODE`,
+`DSH_HOME`, `DEEPSEEK_BASE_URL`, `OMP_AUTH_BROKER_URL`, and the base URLs and config
+directories of the others) are dropped for a user without the bypass grant.
+
+Two things that deliberately do **not** travel as environment variables: **effort**, because
+an environment variable hard-locks it and blocks `/effort`, and **model**, which is written
+into the case's `.claude/settings.local.json` so that `/model` keeps working.
+
+## Choosing a mode
+
+- **Claude Code** if you want every Codeman feature. Unattended overnight runs, usage-limit
+  auto-resume, the Approvals Inbox, and subagent visualization all assume it.
+- **Codex, OpenCode, Gemini, Antigravity, Grok, OMP** when you prefer that agent or that
+  model. You get the session layer, respawn, cron, Docker, and remote SSH; you do not get the
+  hook-driven features.
+- **DeepSeek Harness** if you want DeepSeek's models with real status signals. It is the one
+  non-Claude mode that reports idle, working and blocked to Codeman itself.
+- **Pi** if you want a fast, unsandboxed agent and you understand what project trust does.
+- **Shell** for the times you want a terminal on your phone with no agent at all. It is a
+  genuinely useful mode, not a fallback.
+
+## Pointing one at your own server
+
+Most of these harnesses can also run against a custom OpenAI-compatible endpoint instead of
+their native cloud backend, for one session at a time, an opt-in feature covered in full on
+[Custom Model Endpoints](Custom-Model-Endpoints).
+
+## Read next
+
+- [Core Concepts](Core-Concepts) - run modes versus location overlays.
+- [Custom Model Endpoints](Custom-Model-Endpoints) - run a harness against your own server.
+- [Settings Reference](Settings-Reference) - model, effort, and permission-mode settings.
+- [Keeping Agents Running](Keeping-Agents-Running) - what idle detection does per mode.
+- [Security](Security) - what skipping permission prompts actually means.

docs/wiki/Autonomous-Loops.md

@@ -0,0 +1,97 @@
+# Autonomous Loops
+
+Two features that go further than "keep the session going": the **Ralph loop**, which works
+a task list to completion in one session, and the **Orchestrator**, which turns a goal into
+a phased plan and drives it across agents.
+
+Both are Claude-only, both are off by default, and neither is where to start. If what you
+want is an agent that keeps working overnight, that is
+[Keeping Agents Running](Keeping-Agents-Running), and it is simpler, better understood, and
+what most people actually use.
+
+## Which one, if either
+
+| You have                                          | Use                                                          |
+| ------------------------------------------------- | ------------------------------------------------------------ |
+| A session that stops too early                     | [Respawn](Keeping-Agents-Running)                             |
+| A written task list to grind through               | Ralph loop                                                    |
+| One large goal that needs planning and checkpoints | Orchestrator                                                  |
+| Work that should start at a certain time           | [Cron Jobs](Cron-Jobs)                                        |
+| Several workers to fan out and supervise           | [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) |
+
+## The Ralph loop
+
+Named after the Ralph Wiggum pattern: keep feeding the agent its own task list until the
+list is empty.
+
+The shape of it:
+
+- The task list lives in a plan file in the case, conventionally `fix_plan.md`.
+- Each cycle the agent reads the plan, works the next incomplete task, and marks progress.
+- Codeman watches the file, tracks todos, and detects stalls.
+- The loop ends when the agent signals completion, when the iteration cap is reached, or
+  when you stop it.
+
+Start it from **Session Options → Ralph / Todo**, or from the wizard on the welcome screen.
+
+| Setting                | What it does                                                             |
+| ---------------------- | ------------------------------------------------------------------------ |
+| Max iterations         | Hard ceiling on cycles.                                                   |
+| Max todos              | Cap on tracked tasks, default 500, oldest evicted first.                   |
+| Todo expiration        | Auto-expiry for stale todos, default 60 minutes.                           |
+| Plan file              | Which file holds the task list.                                            |
+
+A **circuit breaker** sits behind it to stop respawn thrashing: it moves from closed to
+half-open to open, and is reset explicitly from the session's Ralph controls.
+
+Honest assessment: Ralph is functional but is not where development attention goes. It
+predates the respawn presets, which cover most of what people originally used it for with
+less ceremony. Treat it as a specialised tool rather than the headline feature.
+
+Full background, including the upstream pattern it is based on:
+[`docs/ralph-wiggum-guide.md`](https://github.com/Ark0N/Codeman/blob/master/docs/ralph-wiggum-guide.md).
+
+## The Orchestrator
+
+A state machine that turns one goal into a phased plan and drives it to completion:
+
+```
+idle → planning → approval → executing → verifying → (replanning) → completed / failed
+```
+
+- **Planning** turns your goal into phases.
+- **Approval** is yours. You see the plan before anything runs.
+- **Executing** runs each phase, using team agents and the task queue.
+- **Verifying** gates each phase before the next one starts. A failed gate can send it back
+  to replanning rather than forward.
+
+Open it from the Orchestrator panel in the toolbar. State persists in `state.json`, so a
+server restart does not lose an in-flight plan.
+
+Where it differs from Ralph: Ralph is one session grinding a list, the Orchestrator
+coordinates phases and agents with verification between them. It suits work that has a
+natural shape ("migrate this, then update callers, then update the tests") rather than a
+flat backlog.
+
+Architecture: [`docs/orchestrator-loop-architecture.md`](https://github.com/Ark0N/Codeman/blob/master/docs/orchestrator-loop-architecture.md).
+
+## Running any of this safely
+
+Autonomous loops are the features most able to spend money and change code while you are not
+looking. Some habits that pay off:
+
+- **Run them in a case that is a git repository**, on a branch you are willing to throw
+  away. Being able to read the diff afterwards is the whole safety net.
+- **Consider a container.** [Docker Cases](Docker-Cases) gives the agent its own filesystem
+  and network, and one checkbox is all it costs.
+- **Set the iteration cap deliberately.** It is the ceiling on the spend.
+- **Turn on notifications** so a blocked loop reaches you: see
+  [Notifications And Approvals](Notifications-And-Approvals).
+- **Read the run summary and lifecycle log afterwards**, not just the final diff. They show
+  where it went sideways and recovered.
+
+## Read next
+
+- [Keeping Agents Running](Keeping-Agents-Running) - the simpler feature that usually fits better.
+- [Watching Agents Work](Watching-Agents-Work) - seeing what a loop is doing while it runs.
+- [Docker Cases](Docker-Cases) - a sandbox for unattended work.

docs/wiki/Contributing.md

@@ -0,0 +1,125 @@
+# Contributing
+
+The full guide lives in
+[CONTRIBUTING.md](https://github.com/Ark0N/Codeman/blob/master/.github/CONTRIBUTING.md).
+This page is the short orientation, plus how to fix a page in this wiki.
+
+## Where things go
+
+| You have                    | Send it to                                                                                   |
+| --------------------------- | ---------------------------------------------------------------------------------------------- |
+| A bug                       | An [issue](https://github.com/Ark0N/Codeman/issues), with OS, install method, browser, and which CLI the session was running. |
+| A question or setup problem | [Discussions](https://github.com/Ark0N/Codeman/discussions).                                    |
+| An idea                     | [Ideas](https://github.com/Ark0N/Codeman/discussions/categories/ideas), where it gets voted on.  |
+| A small fix                 | Straight to a PR.                                                                                |
+| A bigger feature            | An issue or Discussion first, then build once the design has a nod.                              |
+| A security problem          | Never a public issue. See [SECURITY.md](https://github.com/Ark0N/Codeman/blob/master/.github/SECURITY.md). |
+
+Issues usually get a response within a day, and every release credits its contributors and
+bug reporters by name.
+
+## Dev setup
+
+```bash
+git clone https://github.com/Ark0N/Codeman.git
+cd Codeman
+npm install        # postinstall builds the vendored xterm addon bundles
+npm run dev        # http://localhost:3000
+```
+
+Requirements: Node 22+, tmux, and at least one agent CLI on your PATH.
+
+The frontend is plain JavaScript with no bundler in dev: edit a `.js` or `.css` file and
+reload. The exception is `index.html`, which is read once at server start, so markup changes
+need a restart.
+
+## Before you push
+
+CI runs all of these, so running them locally saves a round trip:
+
+```bash
+npm run typecheck
+npm run lint
+npm run format:check
+npm run check:frontend-syntax
+npm run check:browser-excludes
+npm test -- test/<file>.test.ts   # one file, the normal way
+npm run test:ci                    # the full CI sweep
+```
+
+`npm install` installs a `pre-push` git hook that runs the static checks above (about 10-40s,
+machine-dependent) and blocks a push that would fail them. It skips itself when you push
+something other than the checked-out HEAD, or when the tree has uncommitted changes the
+checks would read. Skip it once with `CODEMAN_SKIP_PREPUSH=1 git push`; a
+`pre-push` hook of your own is never overwritten.
+
+**Never run bare `npm test`.** The default configuration includes browser-driven Playwright
+suites that need a live server, Chromium, and environment-specific baselines; they hang or
+fail on a normal machine. `test:ci` is the honest "run everything".
+
+Tests are tmux-safe by design: under vitest the tmux layer becomes an in-memory mock, so
+tests cannot touch real sessions. If you add a test that binds a port, pick a unique one at
+3150 or above, and never 3000.
+
+## Finding your way around
+
+- Every source file opens with a `@fileoverview` block. Read it before the file; it is the
+  map.
+- [`CLAUDE.md`](https://github.com/Ark0N/Codeman/blob/master/CLAUDE.md) at the repo root is
+  the densest architecture primer there is. It is written for AI coding agents, but its
+  invariants apply identically to humans, and most review feedback traces back to something
+  already written there.
+- [`docs/architecture-invariants.md`](https://github.com/Ark0N/Codeman/blob/master/docs/architecture-invariants.md)
+  holds the deep mechanisms and the history behind each rule.
+
+## Good first contributions
+
+- **A theme skin.** A skin is four things kept in sync, and a static test checks the sync, so
+  if the test passes your skin works.
+- **A language.** The i18n module is dependency-free, English is canonical, and Simplified
+  Chinese is a complete example to copy.
+- **Docs.** If you got stuck and then figured it out, the sentence that would have unstuck
+  you is a pull request.
+- Anything labelled
+  [good first issue](https://github.com/Ark0N/Codeman/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
+
+Worth discussing first: new CLI backends, and real-device testing reports, especially
+mobile, which always find things emulation cannot.
+
+## PR expectations
+
+- One change per PR. Small and focused reviews fast; a grab bag stalls.
+- Target `master`.
+- **Keep your branch mergeable.** A PR with conflicts silently gets no CI runs at all, which
+  is a GitHub quirk rather than a Codeman one. Rebase when conflicts appear.
+- Include or update tests when you change behaviour.
+- Do not bump versions or edit the changelog; releases are handled after merge.
+- AI-assisted contributions are welcome, with one condition: understand what you are
+  submitting, and actually run it. "The model said it works" is not a test.
+
+## Fixing this wiki
+
+These pages are generated from
+[`docs/wiki/`](https://github.com/Ark0N/Codeman/tree/master/docs/wiki) in the main
+repository, and pushed here automatically when master changes.
+
+**Editing a page in the browser will be overwritten by the next sync.** Send a pull request
+against `docs/wiki/` instead. It is plain markdown, and a documentation PR is a genuinely
+useful contribution.
+
+Conventions for wiki pages:
+
+- Links between pages use the wiki form: `[Remote Access](Remote-Access)`, no `.md`.
+- Links into the repository are absolute `https://github.com/Ark0N/Codeman/blob/master/...`
+  URLs.
+- Images are referenced from the main repository over raw URLs rather than being copied into
+  the wiki.
+- Say what the default is, especially when it is off. Most of Codeman is opt-in.
+- Label Claude-only behaviour every time it appears. Nine of the ten run modes are not
+  Claude.
+
+## Conduct
+
+Be kind, be direct, assume good faith. Report unacceptable behaviour privately via the
+contact in
+[SECURITY.md](https://github.com/Ark0N/Codeman/blob/master/.github/SECURITY.md).

docs/wiki/Core-Concepts.md

@@ -0,0 +1,192 @@
+# Core Concepts
+
+The five ideas the rest of the manual assumes: cases, sessions, run modes, location
+overlays, and tmux. Plus what actually persists, and where it lives on disk.
+
+## Case
+
+A **case** is a named working directory that Codeman remembers. It is the unit you pick in
+the toolbar before hitting Run, and every session belongs to exactly one.
+
+A case is not a container or a sandbox. It is a folder plus a name plus a little
+Codeman-side configuration:
+
+- Which CLI the Run button should default to.
+- Per-case toggles (Agent Teams, 1M Opus context).
+- Where it runs, if it is not the local filesystem: see [Location overlays](#location-overlays).
+
+Three ways to get one, all under **+** next to the case picker:
+
+| How               | Result                                                                                                 |
+| ----------------- | ------------------------------------------------------------------------------------------------------ |
+| **Create New**    | A fresh `~/codeman-cases/<name>` with a scaffolded `CLAUDE.md`.                                          |
+| **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.
+
+## Session
+
+A **session** is one CLI process running in one tmux session, streamed to your browser.
+
+Sessions are named `w<n>-<case>`, so `w1-myproject` is the first worker in the `myproject`
+case. Each has a stable id, and that id is what the API, the wait primitives, and every
+event use.
+
+Several sessions can share one case. That is the normal way to parallelize: three workers
+in the same repo, three tabs, one case.
+
+A session carries state the case does not:
+
+- Its run mode, model, effort level, and environment overrides.
+- Its respawn configuration and Ralph loop state.
+- Its terminal scrollback.
+- Its owner, in [Multi-User Mode](Multi-User-Mode).
+
+## Run mode
+
+The **run mode** is which CLI the session runs: `claude`, `opencode`, `codex`, `gemini`,
+`antigravity`, `pi`, `grok`, `deepseek`, `omp`, or `shell`. It is chosen at start and does not change afterwards; to
+switch, start another session.
+
+Claude is the reference mode. Nine of the ten are not Claude, and a number of Codeman
+features are Claude-only for structural reasons rather than missing effort: they depend on
+Claude Code's hook system or on parsing its terminal output. Every such feature is labelled
+Claude-only where it appears, and [Agent CLIs](Agent-CLIs) lists them in one place.
+
+## Location overlays
+
+Where a case runs is **separate from** which CLI it runs. There are three locations:
+
+| Location       | What happens                                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------------------ |
+| **Local**      | The default. tmux and the CLI run on the Codeman host.                                                        |
+| **Docker**     | One long-lived container per case; sessions `docker exec` into it. See [Docker Cases](Docker-Cases).           |
+| **Remote SSH** | A durable tmux server on the remote host, fronted by a local pane running `ssh`. See [Remote SSH Sessions](Remote-SSH-Sessions). |
+
+This matters because it is a common source of confusion: Docker is **not** an eleventh run
+mode. All ten run modes work in all three locations. A case is docker-backed or
+ssh-backed; a session is claude or codex or shell.
+
+**Web tabs** are the other thing that is not a session. A saved dashboard URL renders as a
+tab beside your agents, but there is no PTY, no tmux, and no respawn behind it. See
+[Web Tabs](Web-Tabs).
+
+## Why tmux
+
+tmux is a hard requirement, and it is the reason Codeman behaves the way it does.
+
+The agent runs inside a tmux session. Codeman attaches to it, the same way your terminal
+would. That indirection buys:
+
+- **Survival.** The agent outlives your browser tab, your network, your laptop lid, and a
+  restart of the Codeman server itself.
+- **Real scrollback.** History is held by tmux, so reconnecting replays what happened while
+  you were gone instead of starting from blank.
+- **Attach from anywhere else.** The same session is reachable from a terminal over SSH
+  with `codeman tui`, or plain `tmux -L codeman attach`.
+- **Secrets off the command line.** Environment overrides are injected with socket-scoped
+  `tmux setenv` rather than being visible in the spawn command.
+
+The socket is `tmux -L codeman`, separate from your personal tmux server, so Codeman
+sessions never appear in a bare `tmux ls`.
+
+## What persists
+
+| Survives                                     | Does not survive                                    |
+| -------------------------------------------- | --------------------------------------------------- |
+| Closing the browser                          | `tmux -L codeman kill-server`                        |
+| Losing the network                            | A machine reboot (tmux dies with it)                 |
+| Restarting the Codeman server                 | Killing the session from the UI                      |
+| `codeman web --stop`                          |                                                      |
+| A dropped SSH link, for remote cases          |                                                      |
+| A container restart, for docker cases         |                                                      |
+
+Conversation history is a separate question: Claude transcripts live in `~/.claude/`, so a
+conversation can be resumed even after the tmux session is gone. That is what the welcome
+screen's **Resume Conversation** list offers.
+
+## State on disk
+
+Everything Codeman knows lives under `~/.codeman/`:
+
+| File                                     | Holds                                                                |
+| ---------------------------------------- | -------------------------------------------------------------------- |
+| `state.json`                             | Sessions, settings, respawn config, orchestrator state, cron jobs.    |
+| `settings.json`                          | User preferences that sync across your devices.                       |
+| `mux-sessions.json`                      | tmux recovery data.                                                   |
+| `session-lifecycle.jsonl`                | Append-only audit log of session starts, exits, and kills.            |
+| `linked-cases.json`                      | Registered cases.                                                     |
+| `remote-hosts.json`, `docker-hosts.json` | Location overlay configuration.                                       |
+| `webviews.json`                          | Saved dashboard URLs.                                                 |
+| `users.json`                             | Multi-user accounts, mode 0600.                                       |
+| `push-*.json`                            | Web push keys and subscriptions.                                      |
+| `certs/`                                 | Self-signed TLS for `--https`.                                        |
+
+None of it needs root, none of it leaves the machine, and deleting `~/.codeman/` resets
+Codeman to a fresh install without touching your code.
+
+## Instances
+
+The data directory and the tmux socket are both **process wide**. Two Codeman servers
+started on one machine share them, which means the second one discovers the first one's
+live sessions and attaches to them, resizing and mutating sessions you did not expect it to
+touch.
+
+To run two on purpose, give each its own instance name:
+
+```bash
+CODEMAN_INSTANCE=beta CODEMAN_PORT=5000 codeman web
+```
+
+That scopes the data directory and the tmux socket together, which is the only safe way to
+do it. `CODEMAN_DATA_DIR` and `CODEMAN_TMUX_SOCKET` can be set individually if you need
+them apart, but setting only one of the two reproduces exactly the problem you were trying
+to avoid.
+
+## Hooks
+
+For Claude sessions, Codeman writes a hooks configuration into the case so Claude Code can
+report events back: a permission prompt appeared, the turn finished, the agent went idle, a
+task completed. Those events drive tab alerts, the Approvals Inbox, notifications, and the
+wait primitives.
+
+This is why some features are Claude-only. The one partial exception is DeepSeek Harness,
+whose terminal front door reports idle, working and blocked to Codeman over the harness's
+own supervisor contract, so it gets the hook-driven signals without a hook file. The other
+CLIs have no equivalent, so for them Codeman falls back to watching terminal output, which
+is coarser: it can see that something happened, not what it was.
+
+See [Hooks And Integrations](Hooks-And-Integrations).
+
+## Vocabulary
+
+| Term            | Means                                                                        |
+| --------------- | ---------------------------------------------------------------------------- |
+| **Case**        | Named working directory.                                                      |
+| **Session**     | One CLI in one tmux session.                                                  |
+| **Run mode**    | Which CLI: claude, opencode, codex, gemini, antigravity, pi, grok, deepseek, omp, shell. |
+| **Respawn**     | Restarting the CLI on idle to keep an unattended run going.                   |
+| **Ralph loop**  | An autonomous single-session task loop.                                       |
+| **Orchestrator**| A phased plan driven across multiple agents.                                  |
+| **Subagent**    | An agent the CLI spawned itself, shown live in its own window.                |
+| **Web tab**     | A saved dashboard URL rendered as a tab. Not a session.                       |
+| **Instance**    | One Codeman server with its own data directory and tmux socket.               |
+
+## Read next
+
+- [The Dashboard](The-Dashboard) - what the UI is showing you.
+- [Agent CLIs](Agent-CLIs) - the ten run modes in detail.
+- [Keeping Agents Running](Keeping-Agents-Running) - respawn, idle detection, usage limits.
+- [`docs/architecture-invariants.md`](https://github.com/Ark0N/Codeman/blob/master/docs/architecture-invariants.md) - the mechanisms behind all of this, for contributors.

docs/wiki/Cron-Jobs.md

@@ -0,0 +1,161 @@
+# Cron Jobs
+
+Saved, named jobs that start a session and send it a prompt on a schedule. Cron for agent
+sessions: *every weekday at 03:00, open a Claude session in `~/proj` and tell it to update
+dependencies and open a PR.*
+
+The ⏰ **Cron** header button is opt-in. Turn it on in
+**App Settings → Header & Panels**.
+
+## Creating a job
+
+1. Click **⏰ Cron**, then **+ New Job**.
+2. Give it a name, pick the agent type and working directory.
+3. Write the prompt, or point at a file containing it.
+4. Choose a schedule and leave **Enabled** on.
+5. **Save**. The job appears with its computed next run.
+
+**Run Now** fires it immediately without touching the schedule, which is the fastest way to
+find out whether the prompt does what you meant.
+
+## The fields
+
+| Field                    | Notes                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------------- |
+| **Name**                 | Also used as the created session's name.                                                     |
+| **Agent type**           | Any run mode, including `shell`.                                                             |
+| **Working directory**    | Validated when you save **and** again when the job fires. Blocked system trees are refused.  |
+| **Launch command**       | Shell jobs only. Sent as the first line once the shell is up, before the prompt.             |
+| **Prompt**               | Inline text, or a path to a file read at fire time.                                          |
+| **Input mode**           | `typed` behaves like a human typing. `paste` writes directly.                                |
+| **Schedule**             | `once`, `interval`, `daily`, or `weekly`.                                                    |
+| **Enabled**              | Disabled jobs never fire on their own. **Run Now** still works.                              |
+| **Concurrency policy**   | What to do if sessions of the same type are already running.                                 |
+| **Auto-close previous**  | Recurring jobs only. Closes the session the previous run created. Default on.                |
+| **Notes**                | Free text for you.                                                                           |
+
+## Schedules
+
+All wall-clock times are in the **server's local timezone**, not your browser's. A job set
+for 03:00 fires at 03:00 where the server is.
+
+| Type       | Behaviour                                                                                          |
+| ---------- | -------------------------------------------------------------------------------------------------- |
+| `once`     | Fires at an absolute time, then disables itself. A job missed because the server was down still fires once on the next tick. |
+| `interval` | Every N minutes, from 1 minute to a year.                                                            |
+| `daily`    | At `HH:MM` every day. If today's time has passed, the next run is tomorrow.                          |
+| `weekly`   | At `HH:MM` on the weekdays you pick.                                                                 |
+
+Interval jobs re-anchor to when they actually fired, not to an ideal cadence, so a slow tick
+or a server restart shifts later runs slightly. That drift is accepted rather than corrected.
+
+## Prompts are single line
+
+This is the rule people trip over. Programmatic input into an agent session is single line
+everywhere in Codeman, because the terminal UIs these CLIs use treat a newline as submit. A
+multi-line prompt would be silently mangled, so it is **rejected** instead: the form refuses
+it, and a prompt file whose contents are multi-line fails the run with a clear message.
+
+For anything longer than a sentence, put the instructions in a file and make the prompt tell
+the agent to read it:
+
+```
+read TASKS.md and work through it
+```
+
+That is also easier to edit than a job field.
+
+### Prompt files
+
+Reading the prompt from a file at fire time is useful when the instructions change more
+often than the schedule. The path is confined to the job's working directory, symlinks are
+resolved before the check, sensitive trees are refused, and the file has to be a regular
+file under 1 MiB.
+
+If any of that fails, the run is recorded as failed and **no session is created**.
+
+## Concurrency
+
+Applies to scheduled runs only, never to **Run Now**:
+
+| Policy                          | Behaviour                                                                             |
+| ------------------------------- | -------------------------------------------------------------------------------------- |
+| `warn_only`                     | Always launch. The count of live same-type sessions is shown but does not block.        |
+| `skip_if_same_agent_running`    | Skip this fire if another live session of that mode exists.                             |
+
+The skip policy has the details you would want it to have:
+
+- Only **live** sessions block. A tab whose CLI already exited does not count.
+- Sessions the job created on its own previous runs never block it, otherwise a recurring
+  job would deadlock on itself after the first fire.
+- A skipped `once` job is not consumed. It stays armed and fires when the blocker goes away.
+- Consecutive skips are collapsed into one record per streak, so a perpetually skipped job
+  cannot bloat your state file.
+
+## Run history
+
+Every fire is recorded per job, with a status:
+
+| Status    | Meaning                                                              |
+| --------- | -------------------------------------------------------------------- |
+| `created` | The run started and a session was created.                            |
+| `skipped` | The concurrency policy blocked it. Not counted as a run.              |
+| `failed`  | The prompt could not be resolved, or the working directory was gone.  |
+
+The schedule is advanced **before** the session launches, so a slow start cannot cause the
+same job to re-trigger.
+
+## Cron versus the other autonomy features
+
+| Want                                                | Use                                                     |
+| --------------------------------------------------- | ------------------------------------------------------- |
+| Start work at a specific time                        | Cron                                                     |
+| Keep an existing session working                     | [Keeping Agents Running](Keeping-Agents-Running)         |
+| Drive one goal to completion across phases           | [Autonomous Loops](Autonomous-Loops)                     |
+
+There is also an older, deliberately separate `ScheduledRun` concept behind
+`/api/scheduled`: a run-now, duration-bounded loop with no recurrence and no saved jobs. The
+two systems never interact, and Cron is the one you want.
+
+## From the API
+
+```bash
+API=http://localhost:3000
+
+curl -s -X POST "$API/api/cron/jobs" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "nightly-deps",
+    "agentType": "claude",
+    "workingDir": "/home/me/proj",
+    "promptMode": "inline_text",
+    "promptText": "Update dependencies and open a PR",
+    "inputMode": "typed",
+    "scheduleType": "daily",
+    "dailyTime": "03:00",
+    "enabled": true,
+    "concurrencyPolicy": "warn_only"
+  }' | jq
+
+curl -s "$API/api/cron/jobs" | jq
+curl -s -X POST "$API/api/cron/jobs/<jobId>/run" | jq
+curl -s "$API/api/cron/jobs/<jobId>/runs" | jq
+```
+
+Add `-u admin:"$CODEMAN_PASSWORD"` when a password is set, and `-k` with the `https://` URL
+on an HTTPS install.
+
+## Gotchas
+
+- **Times are the server's, not yours.** Obvious until you are travelling.
+- **A `pi` job starts slowly.** The readiness poll looks for markers pi does not print, so it
+  burns its poll budget before sending the prompt. The job still works.
+- **A deleted working directory fails the run**, by design, rather than creating a session
+  somewhere unexpected.
+- **Auto-close only touches sessions this job created.** Your own tabs are never closed.
+
+## Read next
+
+- [Keeping Agents Running](Keeping-Agents-Running) - continuing work rather than starting it.
+- [Notifications And Approvals](Notifications-And-Approvals) - hearing about a job that got stuck.
+- [`docs/cron-guide.md`](https://github.com/Ark0N/Codeman/blob/master/docs/cron-guide.md) - the complete reference, including the API and SSE events.

docs/wiki/Custom-Model-Endpoints.md

@@ -0,0 +1,189 @@
+# Custom Model Endpoints
+
+Point a harness at your own OpenAI-compatible server instead of its native cloud backend, for
+one session at a time. "Custom endpoint" covers **local** hardware (llama.cpp, Ollama, vLLM,
+a home GPU rig, DGX Spark, Strix Halo) and **cloud** services (Azure AI Foundry's
+OpenAI-compatible endpoint, OpenRouter, a company gateway) alike, anything answering
+`GET /v1/models` and `POST /v1/chat/completions` in the standard shape.
+
+**Off by default.** Turn it on in App Settings → Models → **Custom model endpoints**.
+
+## Adding an endpoint
+
+Still in App Settings → Models → Custom model endpoints:
+
+1. **+ Add endpoint** — give it an id, a label, and the base URL (`http://192.168.1.50:8080`,
+   say). An API key is optional; most local servers don't check one.
+2. **Discover** — fetches the endpoint's own model list over `GET /v1/models` and stores it.
+3. Pick a **default model** from what was discovered. This is the model the Run-menu entry
+   applies directly when only one model is discovered; with two or more, it's just the one
+   pre-marked in the picker dialog described below, not a silent default.
+
+Endpoint management is admin-only in multi-user mode, the same as remote hosts and Docker
+hosts — these are machine-level infra, not a per-user setting.
+
+**Model lists refresh themselves.** Every saved endpoint is re-discovered automatically every
+5 minutes in the background, so a model the server starts serving later — or stops serving —
+shows up without another manual click of **Discover**. One endpoint being unreachable on a
+given cycle (powered off, wrong network) never blocks the others from refreshing.
+
+**Context length is picked up automatically where it can be, safely.** Against a
+llama.cpp/llama-swap server, discovery also learns each _currently loaded_ model's real
+context window and applies it to the launched session (Claude Code today — see below), so
+the harness stops assuming a large default window for a model name it doesn't recognise and
+overflowing a much smaller real one. It's deliberately never probed for a model that isn't
+already loaded, since asking a llama-swap server about an unloaded model can trigger an
+actual, slow model swap as a side effect — a model just not currently loaded keeps whatever
+context length an earlier cycle already learned for it instead.
+
+## Running a session against one
+
+With the setting on and at least one endpoint carrying a discovered model, the **Run**
+dropdown grows a **Custom Endpoints** section: one entry per harness that can redirect to a
+custom endpoint, per saved endpoint, e.g. "Claude Code (llama.cpp)". Picking one starts a
+session on that harness exactly the way its own entry would. It is a one-off "try this
+endpoint" action, not a sticky mode — the plain **Run** button still means "this harness,
+native cloud" afterward, and a fresh session never inherits whatever the last one was
+pointed at.
+
+**Which model it uses depends on how many the endpoint has discovered.** With exactly one,
+the session launches straight away on that model — nothing to choose. With two or more, a
+small dialog asks which one to use for this launch before starting the session; the
+endpoint's default model, if set, is marked but not auto-picked, so a launch can deliberately
+use a different one without changing the saved default. The list is not raw discovery order
+either: the model llama-swap reports loaded and ready is moved to the top and tagged
+**Currently loaded**, and when nothing is loaded, the model you last launched on this harness
+and endpoint pair is moved up instead and tagged **Last used** (a per-device browser value, so
+another device starts from its own history). The default model keeps its own **Default** pill
+in both cases, and nothing is ever auto-chosen: the promoted row is simply the one under your
+thumb.
+
+**For opencode, Codex, Gemini, Pi, Grok, DeepSeek and OMP, picking an entry launches
+straight onto the endpoint** — no restart, because the endpoint is applied before the
+session's process ever starts. **Claude still restarts the harness's process in place** —
+same tab, same conversation (`--resume`) — after a normal native launch, since that restart
+is far less jarring for Claude than for the other seven, whose own TUI can fully
+reinitialize on a restart. Either way, every supported harness reads its endpoint config at
+process start, never per turn, so there is no live hot-swap while a turn is running.
+
+Picking an entry that launches a **brand-new** Claude session waits (up to 20 seconds) for it to
+finish its own startup before applying — a freshly started CLI reports itself as busy for its
+boot sequence, and applying to a genuinely busy session is refused so a real, in-progress
+turn is never interrupted out from under you. A session that is still busy after that wait
+(a very slow-starting CLI, or one you started typing into right away) surfaces that refusal
+as an ordinary error, which now stays on screen with a close button instead of vanishing
+after a few seconds — read it, it names the actual reason rather than a generic failure.
+
+Entries are hidden entirely for a session in a **remote (SSH) or Docker case** — support for
+redirecting those hasn't landed yet, see below. The picker also only appears in the desktop
+**Run** dropdown; the phone home screen builds its own run picker separately and does not
+currently offer these entries.
+
+**Against llama-swap, applying a selection also starts the actual model load, rather than
+waiting on your first prompt to do it.** llama-swap has no "switch model" button of its own
+— the only thing that starts a swap is a real request naming the model, and confirmed live:
+just applying a selection never reached llama-swap's own logs at all until something asked
+it to load. Picking an entry now also sends the smallest real request that will trigger
+that load, in the background, the moment the target model isn't already loaded and ready.
+
+**The centred loading banner has no countdown and no automatic timeout — it waits as long as
+it takes, and tells you so.** When it knows the model's discovered file size (its GB figure,
+when llama-swap states one) it's shown too, e.g. "Loading qwen3.8-27b (16.4 GB) on
+llama-swap — this can take a while depending on your hardware and the model size." An
+earlier version tried to estimate and enforce a time limit, but real load time depends on
+hardware this feature has no way to know, so a fixed number was always a guess — worse, one
+that could kill a genuinely slow load partway through. If it really is taking too long, a
+**Cancel** button right on the banner ends the wait and **closes the session that load was
+for**, on your own call rather than a guessed deadline.
+
+**The banner also shows a real, live second line of what llama.cpp itself is doing** — not
+a made-up progress phase, the actual next line the `llama-server` process printed, e.g.
+"llama.cpp: load_model: loading model '/models/.../Qwen3.8-27B.gguf'" then later
+"llama.cpp: llama_server: model loaded". It comes straight from llama-swap's own event
+feed, filtered down to just the backend process's own output (not llama-swap's own request
+logging), and stays on whatever it last said once the load goes quiet, rather than
+clearing back to nothing.
+
+**You'll also be told if a session's model gets swapped out from under it later, not just
+at launch.** The conflict warning above only fires at the moment you launch or apply a
+model — llama.cpp only runs one model at a time, so if a DIFFERENT session using the same
+endpoint later triggers its own load, whatever was loaded before (including a session you
+already had running) gets silently evicted, with no warning at that instant since nothing
+conflicted when it was first set up. A background check (every 20 seconds) catches this
+after the fact and shows a toast naming which session lost its model and what's loaded now
+— so you know before typing into that session that it's about to reload (and, in turn,
+evict whatever displaced it).
+
+**Claude Code specifically gets three extra fixes applied automatically:**
+
+- Its discovered context length (see above) is passed through as
+  `CLAUDE_CODE_MAX_CONTEXT_TOKENS`, so it doesn't send a full-size prompt against a much
+  smaller real local context and overflow it.
+- Its session runs with an isolated `CLAUDE_CONFIG_DIR`, so the injected API key never sits
+  in the same directory as a stored claude.ai login — that combination is harmless for actual
+  requests (the API key wins) but the CLI still prints a "both claude.ai and
+  ANTHROPIC_API_KEY set" warning about it, which this avoids entirely. The isolated directory
+  keeps a link back to your real session history so the response viewer and similar features
+  still work for that session. That isolated directory starts with no prior approvals of its
+  own, so Codeman also pre-approves the injected key the same way answering Claude Code's own
+  "Detected a custom API key" prompt once would — without it, that prompt would otherwise
+  reappear on every single launch with nobody there to answer it.
+- **That same fresh isolated directory also looks like a brand-new Claude Code profile**, so
+  without this fix it replayed the WHOLE first-run sequence every single launch: the theme
+  picker, the security-notes screen, the "trust this folder?" dialog, and a one-time warning
+  about running with permissions bypassed — none of which a real, already-used profile shows
+  again. Codeman now pre-seeds that same "already been through this once" state (onboarding
+  completed, this session's own project marked trusted, the bypass-permissions warning
+  acknowledged) so a custom-model launch reaches the actual conversation exactly as fast as a
+  native cloud one does, instead of stopping at a wizard with nobody there to click through it.
+
+**If a model's real context is too small for Claude Code to even get started, you get a
+warning instead of a confusing failure.** Claude Code's own system prompt and tools take up
+roughly 40K tokens on their own, before you've typed anything — a small local model with a
+smaller real context than that fails outright on the very first message, no matter what
+context size Codeman tells it to expect (raising the declared context only changes when
+Claude Code trims _conversation history_, and there is none yet on message one). Picking
+such a model now shows an in-app dialog naming the model, its discovered context and what's
+needed, before anything launches or restarts, with the fix spelled out: reconfigure
+llama-swap to give that model (or a smaller one) an explicit larger context instead of
+relying on auto-fit (`--fit-ctx`), which sizes the context around fitting the biggest model
+rather than the biggest context — for example adding `-c 65536` to that model's llama-swap
+entry. "Launch anyway" is still there if you want to try regardless.
+
+## Which harnesses actually work
+
+| Harness                                  | Status                                                                                                                                                                                                               |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Claude Code, opencode, Pi, Grok, OMP** | Verified end-to-end against a real local server.                                                                                                                                                                     |
+| **Codex**                                | Config is correct, and plain chat can work against a server that speaks the Responses API — but a real tool-call attempt comes back as inert text instead of running, so it's still not usable for real coding work. |
+| **Gemini**                               | Fails with an auth error gemini-cli raises once redirected. Unresolved; don't rely on it yet.                                                                                                                        |
+| **DeepSeek**                             | The original 404 is root-caused and fixed (DeepSeek Harness's own code was missing a `/v1` most local servers require) — not yet re-run against a real `dsh` install to confirm end-to-end.                          |
+| **Antigravity**                          | No known custom-endpoint mechanism at all. Not offered.                                                                                                                                                              |
+
+Which harnesses show up in the Run-menu picker is read live off Codeman's own CLI registry,
+not a fixed list here, so this table can go stale before this page does — a greyed-out or
+missing entry is the more current answer.
+
+## What it does not do
+
+- **No remote or Docker sessions yet.** Both restart their agent differently under the hood
+  (reattaching a durable tmux session rather than relaunching the process), so redirecting
+  them needs its own plumbing that hasn't been built.
+- **No live hot-swap mid-conversation.** Applying a selection always restarts the process.
+- **No button to un-point a session from the UI yet.** Clearing back to native cloud is an
+  HTTP call (`POST .../custom-model {"clear": true}`) or deleting the session; the settings
+  panel manages saved endpoints, not what a running session is currently pointed at.
+- **Nothing is shared with your real cloud credentials.** The endpoint's own key, if any,
+  never touches your Anthropic/OpenAI/Google login — a custom endpoint is a separate,
+  explicit choice per session.
+
+## Security
+
+An endpoint's base URL can't point at a link-local or cloud-metadata address (both at save
+time and against the address it actually resolves to), the same guard Web Tabs uses for
+saved dashboards. Endpoint records and any per-session config files a harness needs are
+written with owner-only permissions. See
+[custom-model-endpoints-plan.md](https://github.com/Ark0N/Codeman/blob/master/docs/custom-model-endpoints-plan.md)
+in the repository for the full design reasoning, including why this feature closed a
+pre-existing gap in how session environment overrides were guarded rather than opening a new
+one.

docs/wiki/Docker-Cases.md

@@ -0,0 +1,233 @@
+# Docker Cases
+
+Run a case inside its own container instead of directly on your host: for isolation, for a
+reproducible toolchain, and for the ability to pick the whole environment up and move it to
+another machine.
+
+A docker case is a **location overlay**, not a run mode. All ten run modes work inside a
+container. See [Core Concepts](Core-Concepts).
+
+## One-time setup: the base image
+
+The container needs an image carrying the agent toolchain (node, the CLIs, git, tmux). It
+builds itself on first use with progress streamed to the UI, or you can build it ahead of
+time:
+
+```bash
+node scripts/build-agent-image.mjs --no-cache
+```
+
+**Always pass `--no-cache`.** The CLIs are installed in a single `npm install -g` layer, so
+a plain rebuild reuses that layer from the cache and the CLIs stay frozen at whatever
+versions the image was *first* built with. This has shipped a broken CLI while reporting a
+successful build.
+
+A zero exit code proves the layers ran, not that the toolchain works. Verify:
+
+```bash
+docker run --rm codeman/agent:base bash -lc \
+  'for c in claude codex gemini opencode agy pi grok dsh omp; do printf "%-9s " $c; $c --version 2>&1 | head -1; done'
+```
+
+The image is secret-free. Credentials are delivered at runtime, never baked in, so exports
+never leak them. A full image lands around 1.6GB.
+
+Prerequisite: Docker or Podman with a reachable daemon.
+
+## The quick way
+
+On **Add Case → Create New**, tick **🐳 Run in an isolated Docker container**. That alone is
+enough: Codeman creates the case folder, spins up a hardened container with sensible
+defaults, and starts the session inside it.
+
+Expanding **Container settings** offers a template:
+
+| Template          | Memory | CPUs | GPUs                                  |
+| ----------------- | ------ | ---- | ------------------------------------- |
+| Small             | 2 GB   | 1    | none                                  |
+| Medium (default)  | 4 GB   | 2    | none                                  |
+| Large             | 8 GB   | 4    | none                                  |
+| GPU               | 8 GB   | 4    | all (needs the NVIDIA container toolkit) |
+
+Disk is elastic: storage grows as data arrives, bounded only by host disk. Changing any
+setting creates a dedicated host profile for that case, so it never mutates the shared
+default.
+
+## The full way
+
+**Add Case → Docker** exposes everything:
+
+| Field                | Meaning                                                                                       |
+| -------------------- | ----------------------------------------------------------------------------------------------- |
+| **Case name**        | As usual.                                                                                        |
+| **Workspace path**   | A real host directory, bind-mounted into the container at the **same absolute path**.            |
+| **Host ID**          | A reusable profile (image, network, resources). Share one across cases to share settings.        |
+| **Network**          | `bridge` (internet on, default), `none` (fully isolated), or a custom bridge.                    |
+| **Advanced**         | Memory and CPU caps, host credential seeding, and whether to resume the last conversation on relaunch. |
+
+The same-absolute-path bind mount is what keeps the File Viewer, attachments, and watchers
+operating on real host bytes rather than a copy.
+
+## One container per case
+
+Exactly one long-lived container per case, shared by every session in it.
+
+- Killing one session kills only that session's in-container tmux. Siblings keep running and
+  the container stays up.
+- Reconnecting after a Codeman restart lands back in the same live agent.
+- A container stop or a host reboot restarts the container and **resumes the last
+  conversation** from the bind-mounted transcript.
+- Deleting the case removes the container. The workspace on the host survives.
+
+## Attaching to a container you already run
+
+Tick **Attach to an existing container** on **Add Case → Docker** to link a case to a
+container that already exists instead of creating one. Codeman only `exec`s into it and
+never creates, starts, stops, restarts or removes it, so a container that is missing or
+stopped fails with a message rather than being fixed for you. Drift detection does not
+apply (the container carries no Codeman configuration label). The full-image export is
+refused, since it would `docker commit` someone else's container, and the workspace export
+skips the pause that keeps an owned container consistent during the capture.
+
+One adopted container can back several cases at different in-container directories, and
+**copy an existing case** pre-fills the form from a sibling on the same container. An exact
+twin (the same container and the same directory) is refused, as is a container another
+user adopted.
+
+Adoption is **admin-only in multi-user mode**. Linking creates Codeman's own container
+with one bind mount that has already been checked; an adopted container's mounts belong to
+whoever started it, and one that mounts `/` hands the adopter the host.
+
+## Credentials
+
+Your existing host logins work inside the container without logging in again. Credentials
+are **seeded**: mounted read-only and copied in once at launch, so in-container CLIs never
+write refreshed tokens back to your host credential stores. Onboarding and trust prompts are
+pre-answered so no wizard appears.
+
+Turn seeding **off** for a sealed sandbox: no host credentials, and with `network: none`, no
+outbound access either. That is the profile for genuinely untrusted work; you log in inside
+the container instead.
+
+Bind mounts are excluded from image capture, so exports stay secret-free.
+
+One consequence worth knowing: Pi, Grok and OMP credentials are seeded per file rather than
+as whole directories, because those directories also hold sessions, extensions, downloads and
+installed packages, which can be gigabytes. So in-container Pi and Grok sessions are
+invisible from the host (`pi -c` and `grok -c` inside a docker case see only that
+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.
+
+To give agents a fixed Git commit identity, set `CODEMAN_AGENT_IMAGE_GIT_USER_NAME` and
+`CODEMAN_AGENT_IMAGE_GIT_USER_EMAIL` together in that same environment (in the Docker
+deployment, set `GIT_USER_NAME` and `GIT_USER_EMAIL` in `docker/.env` instead, which feeds
+both images). An existing `codeman/agent:base` only picks it up after a `--no-cache` rebuild
+and recreated case containers; `docker/README.md` ("Git commit identity") has the details.
+
+## Isolation
+
+Every container runs hardened by default:
+
+- `--cap-drop ALL`
+- `--security-opt no-new-privileges`
+- Non-root, running as your host uid so workspace files stay host-owned
+- PID limit, memory cap with swap pinned to it, `--init`
+- **Never** `--privileged`, and **never** the docker socket
+
+Rootless engines without cgroup-v2 systemd delegation cannot enforce resource caps; linking
+such a host warns that the caps are advisory.
+
+## Configuration drift is refused, not ignored
+
+Editing a docker host's configuration (image, memory, network) after a container exists is
+detected on the next launch by comparing a configuration hash against the container's label.
+A mismatch **refuses the launch** and offers to recreate rather than silently running with
+stale configuration.
+
+Recreating is refused while sessions of that case are live. The workspace and the
+conversation both survive it.
+
+## Moving a case to another machine
+
+**Export**, from the Docker tab:
+
+| Option                     | Contents                                                                  |
+| -------------------------- | ------------------------------------------------------------------------- |
+| **Full image + workspace** | The whole toolchain, installed packages, and files, in one `.tgz`.        |
+| **Workspace only**         | Just the project files. Fast and small.                                    |
+
+The container is paused across the capture so image and workspace are consistent, free space
+is checked first, and the intermediate image is cleaned up. Exports run in the background
+and notify you when the bundle is ready.
+
+**Import** on the other machine: copy the `.tgz` into `~/.codeman/docker-exports/` and
+import it into a new case. The manifest and per-member checksums are verified, the workspace
+tar is extracted with a traversal guard, and the image is loaded under a **quarantined tag**
+so it can never overwrite a local image. The destination supplies its own credentials, so
+nothing secret crosses machines.
+
+## Hooks need to reach the server
+
+In-container hooks (permission events, idle and stop notifications) call back to Codeman
+over the docker bridge gateway. If Codeman binds **loopback only**, which is the default and
+the production configuration, the container cannot reach it and **in-container hooks do not
+fire**.
+
+The session still works fully: idle detection falls back to output-based detection through
+the exec PTY, and with permission prompts skipped there is nothing to forward anyway.
+
+To enable them:
+
+```bash
+CODEMAN_DOCKER_BRIDGE_HOOKS=1
+```
+
+Codeman then starts a second listener bound to the docker bridge gateway that serves **only**
+the hook endpoints and rejects everything else with a 403. The bridge is host-internal, so
+this does not widen your network exposure. Add it to the service unit and restart.
+
+## Limits
+
+- Per-session environment overrides, effort, and per-CLI configuration are **rejected** for
+  docker cases, because they do not cross into the container. Configure the container through
+  the docker host's per-mode command override instead.
+- tmux must exist in the base image. It is a hard prerequisite and is probed when linking a
+  host.
+- On macOS, Docker Desktop takes a dedicated uid path, and memory caps are subject to the
+  VM's own ceiling.
+
+## Read next
+
+- [Core Concepts](Core-Concepts) - why this is an overlay rather than a run mode.
+- [Security](Security) - where containers fit in the model.
+- [Remote SSH Sessions](Remote-SSH-Sessions) - the other overlay.
+- [`docs/docker-cases.md`](https://github.com/Ark0N/Codeman/blob/master/docs/docker-cases.md) - the full reference.

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

@@ -0,0 +1,202 @@
+# Driving Codeman From An Agent
+
+Everything the dashboard does is HTTP, so an agent can do it too. This page is for the case
+that makes Codeman interesting: **Claude Code running inside a Codeman session, spawning and
+supervising other sessions.**
+
+Two routes. Start with the skill.
+
+## The agent skill
+
+A Claude Code skill that teaches the agent the whole API, so you ask in plain English
+instead of pasting endpoint documentation into prompts.
+
+### Install it
+
+| How          | Command                                                     | Scope                                                       |
+| ------------ | ----------------------------------------------------------- | ----------------------------------------------------------- |
+| Skills CLI   | `npx skills add Ark0N/Codeman --skill codeman -g`            | Global, any skills-aware agent.                              |
+| Claude Code plugin | `/plugin marketplace add Ark0N/Codeman`, then `/plugin install codeman@codeman` | Global, through Claude Code's plugin manager. `/plugin update codeman` follows releases. Pick this or `codeman skill install`, not both, or the skill is listed twice (`codeman` and `codeman:codeman`). |
+| Bundled CLI  | `codeman skill install`                                      | Global, at `~/.claude/skills/codeman`.                       |
+| Bundled CLI  | `codeman skill install --case <name>`                        | One case.                                                    |
+| Web UI       | **App Settings → Agents & CLIs → Claude → Agent Skill**      | Injects into each case when a Claude session is created. Off by default. |
+
+`codeman skill uninstall [--case <name>]` reverses the CLI installs, and never touches a
+`skills/codeman` you wrote yourself.
+
+### Then just ask
+
+| You say                                                                                 | What happens                                                                             |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| "What sessions are running right now?"                                                   | Lists them with name, mode, and status. Read-only.                                          |
+| "Start a shell worker on the `myapp` case, run the test suite, tell me if it passes."     | Spawns, waits on a completion marker, reads the exit code, cleans up.                       |
+| "Spin up 3 workers for lint, typecheck and tests, run them in parallel, report failures." | One session per task, all started first, then gathered as each finishes.                    |
+| "Have a claude worker summarize `src/session.ts`, then close it."                         | Spawns, runs the readiness ladder, sends and waits, reads the answer, deletes the session.  |
+| "Watch session w4 and tell me if it gets stuck on a permission prompt."                   | Blocks on the `blocked` signal and surfaces the question to **you**.                        |
+
+Sessions the agent creates get deleted when it is done. You can watch the tabs appear and
+disappear in the dashboard while it works.
+
+### What it will and will not do
+
+- **It self-gates.** Outside a Codeman session it refuses to act and does not guess an API
+  URL, so a global install costs an unrelated Claude Code session nothing.
+- **Unprompted, it may only** spawn sessions, prompt them, and delete ones **it created in
+  that conversation, by exact id**, behind a guard that refuses to delete the agent's own
+  session.
+- **It will not** answer another session's permission prompt on your behalf. It surfaces the
+  question instead.
+- **Deleting a case** (which erases a real directory of your code), bulk kills, respawn,
+  Ralph, cron, orchestrator, and settings writes all require you to ask, naming the target.
+
+Turning the setting back off **does not remove already-injected copies**, because a
+create-time sweep would yank the skill out from under other live sessions sharing that
+directory. Remove them per case with `codeman skill uninstall --case <name>`.
+
+The skill ships with the verb index always loaded, plus on-demand references for the verbs,
+worked multi-worker recipes, endpoint tables, and cross-session messaging. It drives
+DeepSeek Harness workers the same way it drives Claude ones (`spawn_workers alpha
+beta:deepseek` is a mixed fleet in one call), since those are the two modes with real
+completion signals.
+
+## The manual path
+
+The same operations as raw HTTP, for a CI bot, a shell script, or an agent without skill
+support.
+
+### Detect that you are inside Codeman
+
+These are set in every managed session. Read them rather than hardcoding anything:
+
+| Variable                   | Meaning                                                                  |
+| -------------------------- | ------------------------------------------------------------------------ |
+| `CODEMAN_MUX=1`            | You are in a managed tmux session. Never `tmux kill-session`, `pkill claude`, or `pkill tmux`: you will kill yourself or a sibling. |
+| `CODEMAN_API_URL`          | Base URL, with the correct scheme.                                        |
+| `CODEMAN_SESSION_ID`       | Your own session id. Use it to avoid acting on yourself.                   |
+| `CODEMAN_HOOK_SECRET_FILE` | Path to the hook secret.                                                   |
+
+### Rules of the road
+
+Read these before writing any code. Each one has cost somebody an afternoon.
+
+1. **Input is single line and must end with `\r`.** Enter fires only when the payload
+   contains a carriage return. Without it the text sits unsubmitted on the prompt, the
+   request still succeeds, and a combined wait burns its full timeout on a turn that never
+   started. Embedded newlines are stripped rather than rejected, so `"echo A\necho B\r"` runs
+   the joined `echo Aecho B`. One line per call.
+2. **Make input idempotent.** Send a stable `clientId` and a monotonic per-session `seq`. The
+   server deduplicates, so a retry after a dropped connection cannot double-deliver.
+3. **Auth.** With `CODEMAN_PASSWORD` set, use HTTP Basic or the session cookie. A missing
+   `Origin` is allowed, so plain curl works. A `401` replies with the bare string
+   `Unauthorized`, **not** the JSON envelope, so piping it into `jq` throws a parse error
+   instead of showing the failure. Check the status before parsing.
+4. **Envelope.** Most endpoints return `{ "success": true, "data": ... }`. A few legacy GETs
+   return bare bodies, so handle both: `body.data ?? body`.
+5. **Wait instead of polling, and a timeout is not an error.** The wait endpoints answer
+   `200` with `wait.timedOut: true`. Loop over short waits rather than one long call, because
+   tunnels cut idle connections.
+6. **Only `claude` and `deepseek` sessions emit `stop` and `blocked`.** Claude's come from
+   Claude Code hooks, DeepSeek's from the harness reporting its state to Codeman. Shell and
+   the other external CLIs accept only `idle`, `working`, and `exit`; asking for `stop`
+   explicitly there is a `400`, while omitting `until` is always safe. On a shell session
+   `idle` fires **once at startup and never again**, so synchronize hook-less sessions with an
+   output marker instead.
+7. **Nothing reports "ready", so wait for it explicitly.** A new session answers
+   `{"signal":"exit","immediate":true}` until its PID exists, and that means *not started*,
+   not *crashed*. A Claude worker in a fresh case then sits on the CLI's trust dialog; prompt
+   it there and the wait resolves on idle in about two seconds looking exactly like a finished
+   turn, while your text sits stuck in the dialog.
+
+### Recipes
+
+```bash
+API="${CODEMAN_API_URL:-http://localhost:3000}"
+# Add -u admin:"$CODEMAN_PASSWORD" if a password is set, and -k on an HTTPS install.
+
+# What is running
+curl -s "$API/api/sessions" | jq '.data[] | {id, name, mode, status}'
+
+# Spawn a worker in a case
+curl -s -X POST "$API/api/quick-start" \
+  -H 'Content-Type: application/json' \
+  -d '{"caseName":"myapp","mode":"shell"}' | jq
+
+# Send a prompt (note the \r)
+curl -s -X POST "$API/api/sessions/$ID/input" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"run the tests\r","clientId":"my-agent","seq":1}' | jq
+
+# Send and block until the turn finishes (registers the wait BEFORE writing)
+curl -s -X POST "$API/api/sessions/$ID/input" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"summarize src/session.ts\r","wait":["stop"],"waitTimeout":120000}' | jq
+
+# Or wait for a marker in the output, which works on shell sessions too
+curl -s "$API/api/sessions/$ID/wait-output?contains=DONE_17909&from=buffer" | jq
+
+# Read the last answer as clean text (claude, codex, deepseek sessions)
+curl -s "$API/api/sessions/$ID/last-response" | jq -r '.data.text'
+
+# Or read the terminal back
+curl -s "$API/api/sessions/$ID/terminal?tail=4000" | jq -r '.data.output'
+
+# Clean up, by exact id
+curl -s -X DELETE "$API/api/sessions/$ID" | jq
+```
+
+Use `POST /api/quick-start` rather than `POST /api/sessions` when a case might be remote:
+the plain create endpoint validates the working directory locally and has no case concept.
+
+### The split-marker trick
+
+For hook-less sessions, synchronize on a marker in the output. The catch: your own
+keystrokes echo into the output stream, so an unsplit marker matches **before the command
+has run**.
+
+Split it so the typed line never contains the string you are waiting for:
+
+```bash
+M=DONE; R=17909
+# typed: echo ${M}_${R}   →   output contains DONE_17909, the typed line does not
+```
+
+Make it unique per call, because tmux repaints replay old screen text.
+
+### Reading output
+
+For `claude`, `codex` and `deepseek` sessions, read the answer from the transcript rather
+than the screen: `GET /api/sessions/:id/last-response` returns the last reply as clean text
+with no TUI frames or repaint noise. Poll it briefly rather than reading once, because the
+transcript lands slightly after the `stop` signal, so a read immediately after send-and-wait
+returns often comes back empty.
+
+For everything else, use `terminal?tail=`, not `/output`. The latter's text field is empty for every tmux-backed
+session, which is every interactive session. `tail` counts **bytes**, and what comes back is
+terminal data with ANSI sequences included.
+
+## Fan-out, and why it needs care
+
+Wait signals are **edge triggered with no history**. A signal that fires with no waiter
+registered is unobservable afterwards.
+
+So a fan-out must register its waits before or as it dispatches: use send-and-wait per
+worker, or latched output markers. Dispatching all the workers and then waiting on them one
+at a time loses the signals of everyone who finished early.
+
+Send-and-wait registers the waiter **before** the write for the same reason. A separate POST
+followed by a wait races, and reports the previous turn's state.
+
+## Lineage
+
+A create request can name the session that spawned it, through a body field or a header, and
+the dashboard then draws a lineage arc from parent to child. The skill sets it automatically.
+
+It is resolved rather than trusted: an unresolvable parent is dropped silently rather than
+failing the spawn, because a cosmetic field must never break a worker.
+
+## Read next
+
+- [HTTP API](HTTP-API) - the endpoint map and the envelope.
+- [Hooks And Integrations](Hooks-And-Integrations) - events flowing the other way.
+- [Watching Agents Work](Watching-Agents-Work) - seeing the fan-out in the UI.
+- [`skills/codeman/SKILL.md`](https://github.com/Ark0N/Codeman/blob/master/skills/codeman/SKILL.md) - the skill itself.

docs/wiki/FAQ.md

@@ -0,0 +1,258 @@
+# FAQ
+
+The questions that keep arriving in
+[Discussions](https://github.com/Ark0N/Codeman/discussions) and issues. For "why is it
+doing that", go to [Troubleshooting](Troubleshooting) instead.
+
+## The basics
+
+### What is Codeman, in one sentence?
+
+A self-hosted dashboard that runs AI coding agents in persistent tmux sessions on your own
+machine and lets you drive them from any browser, including a phone.
+
+### Is it free? What is the licence?
+
+MIT, free, and open source. There is no paid tier and no account.
+
+### Do I need an API key?
+
+No. Codeman drives agent CLIs you have already installed and logged in yourself. Whatever
+subscription or key that CLI uses is what pays for the tokens. Codeman never collects,
+stores, or refreshes your credentials.
+
+### Which agent CLIs does it support?
+
+Claude Code, OpenCode, Codex, Gemini, Antigravity, Pi, Grok Build, DeepSeek Harness and
+OMP, plus a plain shell, chosen per session. Claude is the reference mode and a few features
+are Claude-only; [Agent CLIs](Agent-CLIs) has the table.
+
+### Does Codeman send my code or prompts anywhere?
+
+No. There is no telemetry, no analytics, and no phone-home. The only network traffic
+Codeman itself makes is between your browser and your server.
+
+Your agent CLI is a separate matter: Claude Code talks to Anthropic, Codex talks to OpenAI,
+and so on. That traffic is the CLI's, on your own account, exactly as it would be in a
+terminal.
+
+Two features do send data outward, both off by default and both stated where they appear:
+voice dictation through your own Claude login, and the Read My Mind prediction call.
+
+### Does it work on Windows?
+
+Through WSL2. Codeman requires tmux. Install it inside WSL, run your agent CLI inside WSL,
+and `http://localhost:3000` works from your Windows browser. Work in the Linux filesystem
+rather than `/mnt/c/...`, which is dramatically slower for file watching and git.
+
+### Is there a mobile app?
+
+The web UI is built for phones and installs as a PWA. There is no App Store or Play Store
+app.
+
+## Sessions and persistence
+
+### Do my agents keep running when I close the browser?
+
+Yes. Agents run in tmux on the server, not in your browser. Close the tab, close the laptop,
+lose the network. When you come back, the session is still there with its scrollback.
+
+The same holds when the Codeman server itself restarts. What does end a session is killing
+the tmux server or rebooting the machine.
+
+### What happens after a reboot?
+
+tmux dies with the machine, so the sessions are gone. Conversations are not: Claude
+transcripts persist on disk, and the welcome screen's **Resume Conversation** list picks
+them back up. Install Codeman as a service and the server itself comes back on boot.
+
+### How many sessions can I run at once?
+
+The design target is 20 sessions and 50 agent windows at 60fps. The hard cap is higher, and
+what you will actually hit first is the CPU and memory of the machine running the agents.
+
+### Can I run Claude Code and Codex side by side?
+
+Yes, that is a normal setup. The run mode is per session, so one case can have a Claude tab,
+a Codex tab, and a shell tab open at the same time, each with its own colour. Some Codeman
+features are Claude-only; [Agent CLIs](Agent-CLIs) lists exactly which.
+
+### Can I attach to a session from a terminal instead of the browser?
+
+Yes. `codeman tui` is a full-screen dashboard of your sessions, with the same
+NEEDS YOU / WORKING / IDLE grouping the web UI uses. `codeman tui --list` prints the
+numbered list and exits, and `codeman tui 2` attaches straight to session 2. `Enter`
+attaches, `F1` comes back. You can also use tmux directly on the `codeman` socket.
+
+## Running unattended
+
+### I hit my Claude usage limit overnight. Can Codeman resume automatically?
+
+Yes, and it is the reason the feature exists. Turn on auto-resume at the top of the Respawn
+tab for that session. When Claude halts on a subscription limit, Codeman parses the reset
+time from the message, waits until two minutes past it, and continues the conversation.
+
+Respawn cycles are blocked while a session is limit-paused, which is what stops a `/clear`
+from wiping the conversation you are waiting to resume. Claude-only.
+
+### Will it keep prompting my agent forever?
+
+Only if you configure it to. Respawn cycling is per session and off unless you turn it on,
+and it has presets ranging from a 60 minute solo session to an 8 hour overnight run. There
+are circuit breakers to stop a thrashing session from spinning indefinitely. See
+[Keeping Agents Running](Keeping-Agents-Running).
+
+### Does an idle session cost tokens?
+
+No. An idle agent is a process waiting for input. Tokens are spent when a turn runs, so what
+costs money is the re-prompting you configured, not the session sitting there.
+
+### Can I schedule work for a specific time?
+
+Yes. [Cron Jobs](Cron-Jobs) saves named jobs on a `once`, `interval`, `daily`, or `weekly`
+schedule; each spins up a session and sends a prompt when due, with per-job run history.
+
+## Access
+
+### How do I reach Codeman from my phone when I am away from home?
+
+Tailscale is the recommended answer: your devices join a private network, Codeman keeps its
+loopback bind, and you get real HTTPS. The installer sets it up, and `install.sh tailscale`
+retrofits it onto an existing install.
+
+A Cloudflare tunnel gives a public URL faster, and requires `CODEMAN_PASSWORD`. Full
+comparison in [Remote Access](Remote-Access).
+
+### Why can't other devices reach Codeman?
+
+Because the default bind is `127.0.0.1`, on purpose. Codeman starts agents with permission
+prompts skipped, so whoever reaches the dashboard can run code on your machine. Exposing it
+is a deliberate step, and [Remote Access](Remote-Access) covers the safe ways.
+
+### My reverse proxy domain is rejected with `403 host not allowed`
+
+The always-on Host-header allowlist blocks DNS rebinding, and it does not know your domain.
+Add it:
+
+```bash
+CODEMAN_ALLOWED_HOSTS='codeman.example.com,.internal.example.com'
+```
+
+A leading dot matches subdomains. Also make sure the proxy forwards WebSocket upgrades.
+
+### Do I have to type a password on my phone?
+
+No. Scan the QR code shown on the desktop dashboard. Tokens are single use and rotate every
+60 seconds. The password remains the fallback.
+
+## Multiple people, multiple instances
+
+### Can several people share one Codeman?
+
+Yes, with `codeman web --multiuser`. Each person gets a login and their own case space, and
+sessions, cases, search, and events are scoped to their owner.
+
+Be clear about what that is: it separates **workspaces**, not operating system accounts.
+Every session still runs as the same OS user, so a determined user's agent can reach another
+user's files. For real isolation, pair users with Docker cases or run separate instances
+under separate OS accounts. See [Multi-User Mode](Multi-User-Mode).
+
+### How do I run a second instance, a beta beside my main one?
+
+Give it its own instance name, which scopes the data directory and the tmux socket together:
+
+```bash
+CODEMAN_INSTANCE=beta CODEMAN_PORT=5000 codeman web
+```
+
+Do not skip this. The data directory and tmux socket are process wide, so a second server on
+the defaults discovers and attaches your live sessions.
+
+## Updating and maintenance
+
+### What is the right way to update Codeman?
+
+| Install route | Update with                                                                 |
+| ------------- | --------------------------------------------------------------------------- |
+| Installer     | Re-run the install one-liner, or **App Settings → System → Updates**.         |
+| npm           | `npm update -g aicodeman`                                                     |
+| git clone     | `git pull && npm install && npm run build`, then restart the service.         |
+
+The in-app updater covers git-clone installs supervised by systemd or launchd. It stashes a
+dirty tree rather than discarding it, and streams progress across the restart. npm installs
+report as non-updatable.
+
+### Will updating kill my running sessions?
+
+No. Sessions live in tmux, so restarting the server reattaches to them.
+
+### Where is my data?
+
+Everything under `~/.codeman/`, with cases created from scratch in `~/codeman-cases/`.
+Nothing needs root and nothing leaves the machine. Uninstalling does not delete either
+directory.
+
+## Features
+
+### What is the difference between respawn, Ralph, and the orchestrator?
+
+- **Respawn** restarts a session's CLI when it goes idle, to keep a long run going. It is the
+  one most people want.
+- **Ralph loop** is an autonomous single-session task loop with its own tracker.
+- **Orchestrator** turns one goal into a phased plan and drives it across agents.
+
+[Keeping Agents Running](Keeping-Agents-Running) and [Autonomous Loops](Autonomous-Loops)
+cover them properly.
+
+### Can agents start and supervise other agents?
+
+Yes. Codeman ships an agent skill that lets an agent inside a session drive the HTTP API:
+list sessions, spawn workers, send prompts, and block until a worker's turn finishes. It is
+off by default and enabled per case.
+
+See [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent).
+
+### Can I run a case in a container?
+
+Yes. One container per case, shared by all its sessions, non-root and capability-dropped by
+default, with your host CLI logins seeded in so nothing asks you to log in again. You can
+export a container plus its workspace and move it to another machine. See
+[Docker Cases](Docker-Cases).
+
+### Can the agent run on a different machine?
+
+Yes. Point a case at a remote host over SSH and the agent runs there, inside a durable
+remote tmux, so a dropped connection does not kill the run. See
+[Remote SSH Sessions](Remote-SSH-Sessions).
+
+### Can I put my Grafana or other dashboards in here?
+
+Yes. Saved URLs render as tabs beside your sessions, proxied through Codeman's own origin so
+that mixed content and frame-blocking headers do not break them. See [Web Tabs](Web-Tabs).
+
+### Why is a feature I read about not on screen?
+
+Most of Codeman's UI is opt-in and defaults to off, so a stock install stays small. Check
+**App Settings → Header & Panels**. [Settings Reference](Settings-Reference) lists the
+defaults.
+
+## Contributing
+
+### How do I request a feature?
+
+Open an [Idea](https://github.com/Ark0N/Codeman/discussions/categories/ideas) and it gets
+voted on. Roadmap decisions happen there.
+
+### How do I contribute code?
+
+[CONTRIBUTING.md](https://github.com/Ark0N/Codeman/blob/master/.github/CONTRIBUTING.md) has
+the full map. Small fixes can go straight to a PR; anything larger starts as an issue or
+Discussion so the design gets a nod first. Skins, translations, and docs are good first
+contributions.
+
+### How do I fix a mistake in this wiki?
+
+These pages are generated from
+[`docs/wiki/`](https://github.com/Ark0N/Codeman/tree/master/docs/wiki) in the main
+repository. Editing a page in the browser gets overwritten on the next sync, so send a PR
+against that directory instead.

docs/wiki/HTTP-API.md

@@ -0,0 +1,173 @@
+# HTTP API
+
+Codeman's HTTP and SSE API is a **stable contract**. Everything the dashboard does goes
+through it, so anything the dashboard can do, a script can do.
+
+This page is the orientation. The complete specification, including every wait semantic and
+the SSE catalogue, is
+[`docs/api-reference.md`](https://github.com/Ark0N/Codeman/blob/master/docs/api-reference.md).
+
+## What is stable
+
+Covered by semantic versioning: endpoint paths under `/api/v1`, the response envelope,
+`errorCode` values, and SSE event names.
+
+Not covered, and free to change in a patch release: on-disk state files, internal modules,
+and anything marked experimental. The full statement is in
+[Versioning](Versioning).
+
+`/api/v1/*` is a versioned alias of `/api/*`. Prefer the versioned form in anything you
+intend to keep.
+
+## The envelope
+
+```json
+{ "success": true, "data": { } }
+```
+
+```json
+{ "success": false, "error": "human readable", "errorCode": "NOT_FOUND" }
+```
+
+A few legacy GET handlers return bare bodies rather than the envelope, so a robust client
+reads `body.data ?? body`.
+
+Branch on `errorCode`, which is stable. The HTTP status is reliable too:
+
+| `errorCode`        | HTTP | Meaning                                          |
+| ------------------ | ---- | ------------------------------------------------ |
+| `INVALID_INPUT`    | 400  | Malformed request or failed validation.           |
+| `UNAUTHORIZED`     | 401  | Authentication required or failed.                |
+| `NOT_FOUND`        | 404  | No such resource.                                 |
+| `SESSION_BUSY`     | 409  | The session is busy.                              |
+| `CONFLICT`         | 409  | Conflicts with current state.                     |
+| `ALREADY_EXISTS`   | 409  | Resource already exists.                          |
+| `OPERATION_FAILED` | 422  | Well formed, could not be completed.              |
+| `RATE_LIMITED`     | 429  | Too many requests.                                |
+| `INTERNAL_ERROR`   | 500  | Unexpected server error.                          |
+
+New error codes are non-breaking. Removing or renaming one is a major change.
+
+**A `401` is the bare string `Unauthorized`, not the envelope.** Piping it into `jq` throws
+a parse error rather than showing the failure, so check the status first.
+
+## Authentication
+
+With no password set, and the default loopback bind, there is none. With `CODEMAN_PASSWORD`
+set, use HTTP Basic or the session cookie:
+
+```bash
+curl -s -u admin:"$CODEMAN_PASSWORD" "$API/api/sessions"
+```
+
+A **missing** `Origin` header is allowed, so curl and CLI tools work unchanged. A
+present-but-foreign origin is rejected by the CSRF guard. On an HTTPS install with the
+self-signed certificate, add `-k`.
+
+## Endpoint map
+
+Roughly 235 handlers across 26 route modules. By domain:
+
+| Domain              | Handlers | Covers                                              |
+| ------------------- | -------- | --------------------------------------------------- |
+| System              | 56       | Status, settings, digest, updates, tunnel.           |
+| Sessions            | 34       | Create, input, terminal, wait, last response, kill.  |
+| Cases               | 34       | Create, link, clone, remote and docker cases.        |
+| Files               | 17       | Preview, edit, raw, attachments, path picker.        |
+| Orchestrator        | 10       | Plans and phases.                                     |
+| Ralph               | 9        | Loop control and configuration.                       |
+| Cron                | 9        | Jobs and run history.                                 |
+| Admin               | 8        | Multi-user administration.                            |
+| Plan                | 8        | Plan orchestration.                                   |
+| Respawn             | 7        | Respawn configuration and presets.                    |
+| Webviews            | 6        | Saved dashboards, plus the proxy.                     |
+| Mux                 | 5        | tmux operations.                                      |
+| Custom model endpoints | 5     | Saved OpenAI-compatible endpoints, and applying one to a session. |
+| Push                | 4        | Web push subscriptions.                               |
+| Read My Mind        | 4        | Intent profiles and prediction.                       |
+| Scheduled           | 4        | The legacy scheduled-run concept.                     |
+| Approvals           | 4        | The inbox, answering, acknowledging.                  |
+| Tab layout          | 2        | Named tab groups per owner.                           |
+| Teams, me, search, hooks, clipboard, telemetry, voice, ws | 1-2 each | |
+
+Each route module documents its own endpoints in its file header.
+
+## Long-polling instead of polling
+
+Three calls block until something happens, so an agent driving Codeman from a shell can wait
+rather than spin:
+
+| Call                                      | Blocks until                                             |
+| ----------------------------------------- | -------------------------------------------------------- |
+| `GET /api/v1/sessions/:id/wait`           | One of a set of lifecycle signals fires.                  |
+| `GET /api/v1/sessions/:id/wait-output`    | A literal string appears in the session's output.         |
+| `POST /api/v1/sessions/:id/input` + `wait`| The input is delivered **and then** a signal fires.       |
+
+Three semantics that break callers who assume otherwise:
+
+1. **A timeout is `200`, not an error.** It answers with `wait.timedOut: true`. Loop over
+   short waits; a single long call gets cut by tunnels and proxies.
+2. **Send-and-wait is not a POST followed by a wait.** It registers the waiter *before*
+   writing, which closes the window where a separate wait sees the session still idle from
+   the previous turn and answers instantly about the wrong turn.
+3. **Signals are edge triggered with no history.** One that fires with no waiter registered
+   is unobservable afterwards. Fan-outs must register their waits as they dispatch.
+
+`wait-output` matches a **literal substring, never a regex.** That is deliberate: no regex
+means no catastrophic backtracking on attacker-influenced output.
+
+Only `claude` and `deepseek` sessions emit `stop` and `blocked`: Claude's come from Claude
+Code hooks, DeepSeek's from the harness reporting its state to Codeman. Shell and the other
+external CLI sessions accept `idle`, `working`, and `exit`.
+
+## SSE
+
+`GET /api/events` is the live event stream. 158 event names, kept in sync between server and
+client with a test that fails on drift.
+
+The heartbeat is a **named** `sse:heartbeat` event rather than an SSE comment, because
+comments are invisible to `EventSource` by specification and a client could not observe
+them. That is what lets the browser detect a stream that has silently stopped delivering.
+
+```js
+const es = new EventSource('/api/events');
+es.addEventListener('session:created', (e) => console.log(JSON.parse(e.data)));
+```
+
+## Quick examples
+
+```bash
+API="${CODEMAN_API_URL:-http://localhost:3000}"
+
+curl -s "$API/api/status" | jq                     # whole-system snapshot
+curl -s "$API/api/sessions" | jq '.data[].name'    # live sessions
+curl -s "$API/api/sessions/unified" | jq           # live + historical, deduped
+curl -s "$API/api/subagents" | jq                  # background agents
+curl -s "$API/api/search?q=deploy" | jq            # cross-session search
+
+# with ID set to a session id:
+curl -s "$API/api/sessions/$ID/last-response" | jq -r '.data.text'   # last answer, from the transcript (claude, codex, deepseek)
+curl -s "$API/api/model-endpoints" | jq                                # saved custom OpenAI-compatible endpoints
+curl -s -X POST "$API/api/sessions/$ID/custom-model" -H 'Content-Type: application/json' \
+  -d '{"endpointId":"local-llama","modelId":"qwen3-27b"}' | jq        # restart the CLI on that endpoint; {"clear":true} undoes it
+```
+
+## Limits
+
+| Limit                 | Default                                    |
+| --------------------- | ------------------------------------------ |
+| Max sessions          | 50                                          |
+| Max agent windows     | 500                                         |
+| Max SSE clients       | 100                                         |
+| Terminal buffer       | 32 MB per session                           |
+| Text payload          | 1 MB                                        |
+| Wait timeout ceiling  | 600 s, and the response tells you what was applied |
+
+Most are environment-overridable. See `src/config/`.
+
+## Read next
+
+- [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) - the practical version, with recipes.
+- [Hooks And Integrations](Hooks-And-Integrations) - events flowing back into Codeman.
+- [Versioning](Versioning) - what the version number promises.
+- [`docs/api-reference.md`](https://github.com/Ark0N/Codeman/blob/master/docs/api-reference.md) - the full specification.

docs/wiki/Home.md

@@ -0,0 +1,136 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/codeman-title.svg" alt="Codeman" height="56">
+</p>
+
+<h3 align="center">Mission control for AI coding agents</h3>
+
+Codeman runs your coding agents on your own machine and puts them behind one dashboard you
+can open from any device. It spawns Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi,
+Grok, DeepSeek Harness, or OMP inside persistent tmux sessions, streams the real terminal to the browser, and keeps
+working while you are away from the keyboard: it re-prompts idle agents, resumes when a
+subscription limit resets, runs jobs on a schedule, and shows every background subagent
+live.
+
+This wiki is the manual. The [README](https://github.com/Ark0N/Codeman) is the overview,
+and the deep internals live in
+[`docs/`](https://github.com/Ark0N/Codeman/tree/master/docs).
+
+```bash
+curl -fsSL https://getcodeman.com/install | bash
+codeman web    # then open http://localhost:3000
+```
+
+---
+
+## Start here
+
+**New to Codeman**
+
+1. [Installation](Installation) - requirements, the installer, npm and git clone routes, updating.
+2. [Quick Start](Quick-Start) - from a running server to a working agent in five minutes.
+3. [Core Concepts](Core-Concepts) - cases, sessions, run modes, and what survives a restart.
+4. [The Dashboard](The-Dashboard) - reading the tab strip, the status dots, and the alerts.
+
+**Already running it**
+
+- [Agent CLIs](Agent-CLIs) - the ten run modes, their setup, and which features are Claude-only.
+- [Mobile Guide](Mobile-Guide) - phone and tablet use, QR login, the touch keyboard bar.
+- [Remote Access](Remote-Access) - Tailscale, Cloudflare tunnel, LAN plus password, QR login.
+- [Keeping Agents Running](Keeping-Agents-Running) - idle detection, respawn cycling, auto-resume on usage limits.
+- [Troubleshooting](Troubleshooting) - symptom-first index of things that actually break.
+
+**Driving it from code**
+
+- [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) - the bundled skill, worker sessions, wait primitives.
+- [HTTP API](HTTP-API) - the envelope, auth, the endpoint map, SSE events.
+- [Hooks And Integrations](Hooks-And-Integrations) - events flowing back into Codeman.
+
+---
+
+## Everything in the manual
+
+### Getting started
+
+| Page                            | What it answers                                     |
+| ------------------------------- | --------------------------------------------------- |
+| [Installation](Installation)    | How do I install it, update it, and remove it?      |
+| [Quick Start](Quick-Start)      | How do I get one agent working right now?           |
+| [Core Concepts](Core-Concepts)  | What is a case, a session, a run mode?              |
+
+### Using it
+
+| Page                                       | What it answers                                            |
+| ------------------------------------------ | ---------------------------------------------------------- |
+| [The Dashboard](The-Dashboard)             | What is the UI telling me?                                 |
+| [Agent CLIs](Agent-CLIs)                   | Which agent should this session run, and how do I set it up? |
+| [Working With Files](Working-With-Files)   | How do I read, edit, and attach files?                     |
+| [Input And Voice](Input-And-Voice)         | How do I talk to an agent, including by voice?             |
+| [Mobile Guide](Mobile-Guide)               | How well does this work on a phone?                        |
+| [Keyboard Shortcuts](Keyboard-Shortcuts)   | What can I drive from the keyboard?                        |
+| [Settings Reference](Settings-Reference)   | What does this setting do, and why did it not follow me to my phone? |
+
+### Keeping agents running
+
+| Page                                                          | What it answers                                     |
+| ------------------------------------------------------------- | --------------------------------------------------- |
+| [Keeping Agents Running](Keeping-Agents-Running)              | How does it run unattended overnight?               |
+| [Notifications And Approvals](Notifications-And-Approvals)    | How do I know an agent needs me, and answer from my phone? |
+| [Cron Jobs](Cron-Jobs)                                        | How do I run an agent on a schedule?                |
+| [Autonomous Loops](Autonomous-Loops)                          | What are the Ralph and Orchestrator loops for?      |
+| [Watching Agents Work](Watching-Agents-Work)                  | How do I see what the subagents are doing?          |
+
+### Where it runs
+
+| Page                                          | What it answers                              |
+| --------------------------------------------- | -------------------------------------------- |
+| [Docker Cases](Docker-Cases)                  | How do I sandbox a project in a container?   |
+| [Remote SSH Sessions](Remote-SSH-Sessions)    | How do I run the agent on another machine?   |
+| [Web Tabs](Web-Tabs)                          | Can my Grafana live in here too?             |
+| [Multi-User Mode](Multi-User-Mode)            | Can several people share one Codeman?        |
+
+### Access and security
+
+| Page                            | What it answers                                            |
+| ------------------------------- | ---------------------------------------------------------- |
+| [Remote Access](Remote-Access)  | How do I reach it from outside this machine, safely?       |
+| [Security](Security)            | What is exposed, what protects it, what do I have to do?   |
+
+### Automation and integration
+
+| Page                                                              | What it answers                              |
+| ----------------------------------------------------------------- | -------------------------------------------- |
+| [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent)    | How does an agent spawn and drive workers?   |
+| [HTTP API](HTTP-API)                                              | What can I call, and what comes back?        |
+| [Hooks And Integrations](Hooks-And-Integrations)                  | How do I wire Codeman into something else?   |
+
+### Operating it
+
+| Page                                          | What it answers                                    |
+| --------------------------------------------- | -------------------------------------------------- |
+| [Running As A Service](Running-As-A-Service)  | How do I keep it up across reboots, and update it? |
+| [Troubleshooting](Troubleshooting)            | Why is it doing that?                              |
+| [FAQ](FAQ)                                    | The questions that keep coming up.                 |
+| [Contributing](Contributing)                  | How do I send a fix?                               |
+| [Versioning](Versioning)                      | What does the version number promise?              |
+
+---
+
+## Requirements at a glance
+
+| Thing        | Needed                                                                      |
+| ------------ | --------------------------------------------------------------------------- |
+| OS           | macOS or Linux. Windows works through WSL2.                                 |
+| Node.js      | 22 or newer.                                                                |
+| tmux         | Required. Sessions live in tmux, which is what makes them survive restarts.  |
+| An agent CLI | At least one of Claude Code, OpenCode, Codex, Gemini, Antigravity, Pi, Grok Build, DeepSeek Harness, OMP. Plain shell sessions need none. |
+| Network      | Binds to `127.0.0.1` by default. Reaching it from another device is a deliberate step: see [Remote Access](Remote-Access). |
+
+Codeman is MIT licensed, self-hosted, and sends no telemetry. Everything runs on your
+machine.
+
+## Getting help
+
+- **Questions and setup help**: [Discussions](https://github.com/Ark0N/Codeman/discussions), especially [Q&A](https://github.com/Ark0N/Codeman/discussions/categories/q-a).
+- **Bugs**: [Issues](https://github.com/Ark0N/Codeman/issues). Include your OS, install method, browser, and which CLI the session was running.
+- **Ideas and roadmap**: [Ideas](https://github.com/Ark0N/Codeman/discussions/categories/ideas).
+- **Security**: never a public issue. See [SECURITY.md](https://github.com/Ark0N/Codeman/blob/master/.github/SECURITY.md).

docs/wiki/Hooks-And-Integrations.md

@@ -0,0 +1,99 @@
+# Hooks and Integrations
+
+Events flowing **back** into Codeman, and the four seams a third party can build against.
+
+## Hooks
+
+Claude Code can run a command when something happens in a session. Codeman writes a hooks
+configuration into each Claude case so those events post back to it, which is what turns a
+terminal into something that can notify you.
+
+| Event                  | Fires when                                      | Drives                                        |
+| ---------------------- | ----------------------------------------------- | --------------------------------------------- |
+| `permission_prompt`    | The agent asks for permission.                   | Red tab alert, Approvals Inbox, push.          |
+| `idle_prompt`          | The agent is waiting for input.                  | Yellow tab alert, the `idle` wait signal.      |
+| `stop`                 | A turn ends.                                     | The `stop` wait signal, idle detection.        |
+| `elicitation_dialog`   | A dialog opens.                                  | Approvals Inbox.                               |
+| `elicitation_complete` | The dialog closes.                               | Clearing the alert.                            |
+| `elicitation_response` | The dialog is answered.                          | Clearing the alert.                            |
+| `teammate_idle`        | An agent-team member goes idle.                  | Team surfaces.                                 |
+| `task_completed`       | A task finishes.                                 | Task tracking, run summary.                    |
+
+This is why several Codeman features are Claude-only. The one partial exception is DeepSeek
+Harness, whose terminal front door reports idle, working and blocked to Codeman over the
+harness's own supervisor contract, so it gets the hook-driven surfaces without any hook
+file. The other CLIs have no equivalent, so for them Codeman watches terminal output, which
+reveals that something happened but not what it was.
+
+### How hooks get installed
+
+Codeman writes them into the case when a Claude session is created. Hook blocks are
+**marker-owned**: Codeman only ever updates a block it wrote, and never touches
+configuration you added yourself.
+
+If tab alerts and approvals never fire in a particular case, that case is missing its hook
+block. Recreating the case rewrites it.
+
+### The hook secret
+
+`/api/hook-event` and `/api/status-telemetry` skip HTTP Basic authentication, because they
+are called from localhost by the CLI itself. When authentication is on, that bypass
+additionally requires a per-instance hook secret, because Codeman cannot tell a genuine
+loopback call from a request arriving through your own loopback reverse proxy.
+
+The secret lives in the data directory, and its path is exported into every managed session.
+
+### Two things that break hooks
+
+- **HTTPS.** Hook callbacks must accept the self-signed certificate. Recent versions
+  self-heal existing cases; older cases need recreating.
+- **Docker cases on a loopback bind.** A container cannot reach `127.0.0.1` on the host, so
+  in-container hooks silently do not fire. Set `CODEMAN_DOCKER_BRIDGE_HOOKS=1` to open a
+  hooks-only listener on the bridge gateway. See [Docker Cases](Docker-Cases).
+
+## Integration seams
+
+Codeman has **no plugin runtime**, and that is a decision rather than a gap. A plugin runtime
+means running third-party code inside a process that spawns agents with your credentials, on
+a server people routinely expose over a tunnel. Codeman's security posture is one of its
+reasons to exist, so it does not trade that away for an extension mechanism.
+
+What exists instead is four documented seams.
+
+### 1. Web tabs
+
+Anything with a web UI can live inside Codeman as a tab, proxied through Codeman's own
+origin. The lowest-effort integration by a wide margin: if your tool has a dashboard, it can
+sit beside the agents with no code at all. See [Web Tabs](Web-Tabs).
+
+### 2. SSE events
+
+`GET /api/events` streams everything Codeman knows: session lifecycle, output, agent
+activity, approvals, cron runs. 158 named events, stable under semantic versioning.
+
+This is the seam for anything that reacts. A bot that pings your chat channel when an agent
+needs a human is a short script over this stream.
+
+### 3. HTTP API and CLI
+
+Everything the dashboard does. Create sessions, send input, block on wait primitives, read
+terminals, manage cron. See [HTTP API](HTTP-API) and
+[Driving Codeman From An Agent](Driving-Codeman-From-An-Agent).
+
+### 4. Hooks
+
+The seam above, in the other direction: your own hook commands can run alongside Codeman's
+in a case, as long as you leave Codeman's marker-owned block alone.
+
+## Publishing an integration
+
+There is no registry to submit to. Share it in
+[Show and tell](https://github.com/Ark0N/Codeman/discussions/300), and if it needs a change
+in Codeman to work properly, open an issue or a Discussion first.
+
+## Read next
+
+- [HTTP API](HTTP-API) - the endpoint map and envelope.
+- [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) - the agent-facing path.
+- [`docs/extending-codeman.md`](https://github.com/Ark0N/Codeman/blob/master/docs/extending-codeman.md) - the seams in full, with examples.
+- [`docs/claude-code-hooks-reference.md`](https://github.com/Ark0N/Codeman/blob/master/docs/claude-code-hooks-reference.md) - upstream hook semantics.

docs/wiki/Input-And-Voice.md

@@ -0,0 +1,147 @@
+# Input and Voice
+
+Getting words into an agent: typing, dictating, and letting Codeman guess. Plus the input
+machinery that only shows up when it goes wrong.
+
+## Typing
+
+Click into the terminal and type. It is a real terminal, so everything the CLI supports
+works, slash commands included.
+
+| Key                          | Effect                                        |
+| ---------------------------- | --------------------------------------------- |
+| `Enter`                      | Send.                                          |
+| `Shift+Enter` / `Ctrl+Enter` | Newline without sending.                       |
+| `Ctrl+C`                     | Copy if text is selected, otherwise interrupt. |
+| `Ctrl+Shift+C`               | Copy, never interrupts.                        |
+| `Ctrl+V`                     | Paste. A clipboard image uploads instead.      |
+| `Ctrl+L`                     | Clear the terminal.                            |
+
+### Exactly-once delivery
+
+Browser input goes through a durable layer rather than a plain socket write. Each prompt
+carries a stable client id and a per-session sequence number, held in local storage until
+the server acknowledges it.
+
+The result is the property you want on a phone: a connection that drops mid-prompt never
+loses the prompt and never delivers it twice. Two browser tabs on the same session coexist,
+and only a reconnect from the *same* tab supersedes the old connection.
+
+## Selecting and copying
+
+Agent CLIs hold the mouse: clicks and drags are reported into the transcript rather than
+selecting text. `Shift+drag` starts a selection anyway, right-click copies it (with nothing
+selected the native context menu is left alone), and `Ctrl+Shift+C` copies without ever
+interrupting. **Auto Copy Selection** in **App Settings → Terminal & Input**, off by
+default, copies the moment you release the mouse. On phones, long-press selects; see
+[Mobile Guide](Mobile-Guide).
+
+## Zero-lag local echo
+
+On touch devices, keystrokes are painted in the terminal immediately and sent when you press
+Enter, instead of waiting for each character to round-trip to the server and back. Over a
+mobile connection that is the difference between usable and not.
+
+![Zero-lag input](https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/images/zerolag-demo-20260728.gif)
+
+The consequence to remember: **text on screen has not necessarily reached the agent yet.**
+It is flushed on Enter. If a prompt appears to have been ignored, press Enter, or the phone
+toolbar's **Enter** button.
+
+Default on for touch devices, off for desktop, and switchable in
+**App Settings → Terminal & Input**.
+
+### Codex is different on purpose
+
+Codex's composer reacts to every keystroke: `/` opens a live-filtering picker, arrows edit
+state on its side, the composer grows as text wraps. Buffering until Enter starved it, so
+Codex sessions use **predictive echo** instead: each keystroke is painted at its predicted
+position while the bytes actually sent stay identical to what you typed. Predictions
+reconcile against the real buffer and only apply while the cursor is on the composer row.
+
+## CJK input
+
+Chinese, Japanese, and Korean input needs an IME, and an IME needs a real text field.
+Turning on CJK input in **App Settings → Terminal & Input** puts an always-visible textarea
+below the terminal that owns composition, then delivers the composed text to the session.
+Ctrl- and Alt-modified navigation keys typed through it reach the CLI as the modified
+sequences, so word jumps and history keys keep working.
+
+## Voice dictation
+
+`Ctrl+Shift+V`, or the microphone button. There are three providers and the default is
+`auto`, which prefers them in this order:
+
+| Provider           | Needs                                          | Notes                                                        |
+| ------------------ | ---------------------------------------------- | ------------------------------------------------------------ |
+| **Claude**         | Claude Code logged in on the server. Opt-in.    | Uses this machine's existing Claude login. No extra key.      |
+| **Deepgram**       | A Deepgram API key.                            | Nova-3, with automatic silence detection.                     |
+| **Web Speech**     | Nothing.                                       | Browser-provided, quality varies.                             |
+
+### Dictating through your Claude login
+
+Off by default; enable it in **App Settings → Voice**.
+
+Claude Code has its own voice mode, but it opens the **host's** microphone, and in Codeman
+the CLI runs headless in a tmux pane while you are in a browser somewhere else entirely. So
+Codeman captures audio in your browser and borrows only the backend: audio goes browser to
+Codeman to Anthropic, and the page never sees the OAuth token.
+
+Two deliberate limits:
+
+- **Credentials are read only.** Codeman never refreshes your Claude token, because a
+  refresh rotates the refresh token and could sign you out of your own CLI. An expired token
+  is reported as expired rather than silently renewed.
+- **Capture is raw PCM** at 16 kHz mono, which requires an AudioWorklet rather than the
+  usual browser recorder.
+
+## Read My Mind
+
+**Claude only, off by default.** Turn it on in **App Settings**, and a 🧠 button appears in
+the header (on phones, in the keyboard bar instead).
+
+It keeps a per-case **intent profile**: goals you or your agent write down, plus the prompts
+you actually submitted in that case. Pressing 🧠 feeds that profile plus live session signals
+to a single model call and shows a predicted next prompt.
+
+What you can do with the result:
+
+- **Send** it, **Insert** it into the composer, or edit it first.
+- Pick one of the alternate suggestions, which swaps into the editable field without losing
+  your edits.
+- **Rethink**, optionally with a steer note, to reject the whole set and try again.
+
+**Nothing is ever sent automatically.** Every path requires a click.
+
+Where the data lives: the profile is keyed by owner and the resolved working directory, so
+it survives `/clear` and respawns. Prompts can contain secrets, so the store is written
+0600 and is deliberately excluded from cross-session search.
+
+Guide: [`docs/readmymind.md`](https://github.com/Ark0N/Codeman/blob/master/docs/readmymind.md).
+
+## Programmatic input
+
+Sending prompts over the API has one rule that catches everyone: **the payload must end with
+`\r`** or Enter is never sent. The request still succeeds, the text sits unsubmitted in the
+composer, and any wait burns its whole timeout on a turn that never started.
+
+Input is also **single line**. Embedded newlines are stripped rather than rejected, so
+`"echo A\necho B\r"` runs the joined `echo Aecho B`. Put multi-line content in a file and
+tell the agent to read it.
+
+See [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent).
+
+## Gotchas
+
+- **Typed text sitting on screen has not been sent.** Press Enter.
+- **`Ctrl+C` with a selection copies.** Clear the selection to interrupt.
+- **Voice needs HTTPS.** Microphone access requires a secure context, same as push
+  notifications.
+- **Read My Mind goes blind for sessions using a relocated Claude config directory**, along
+  with the other transcript-backed features. See [Agent CLIs](Agent-CLIs).
+
+## Read next
+
+- [Mobile Guide](Mobile-Guide) - the keyboard bar and touch input.
+- [Keyboard Shortcuts](Keyboard-Shortcuts) - the full list.
+- [Working With Files](Working-With-Files) - images and attachments as input.

docs/wiki/Installation.md

@@ -0,0 +1,290 @@
+# Installation
+
+Getting Codeman onto a machine, verifying it works, updating it, and removing it.
+
+## Requirements
+
+| Requirement      | Notes                                                                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| **macOS or Linux** | Windows works through WSL2. See [Windows](#windows-wsl) below.                                                                        |
+| **Node.js 22+**  | The installer offers to install it if missing.                                                                                          |
+| **tmux**         | Not optional. Sessions live inside tmux, which is what makes them survive a server restart, a dropped connection, or a closed laptop.    |
+| **An agent CLI** | At least one of [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://opencode.ai), [Codex](https://developers.openai.com/codex/cli), [Antigravity](https://antigravity.google), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Pi](https://pi.dev), [Grok Build](https://github.com/xai-org/grok-build), [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), [OMP](https://github.com/can1357/oh-my-pi). Plain shell sessions need none. See [Agent CLIs](Agent-CLIs). |
+
+Codeman itself sends no telemetry and phones no home. The only network traffic is your
+browser to your server, and whatever the agent CLI you chose does on its own.
+
+## Route A: the installer (recommended)
+
+```bash
+curl -fsSL https://getcodeman.com/install | bash
+```
+
+This installs Node.js, tmux and a build toolchain if they are missing (node-pty ships no
+Linux prebuild, so it compiles from source), clones Codeman into `~/.codeman/app`, and
+builds it.
+
+It starts by printing what it found (git, Node, tmux, build tools, agent CLIs, Tailscale,
+an existing install), then asks everything it needs up front, then does the work
+unattended. You can leave while it builds. What it asks you:
+
+1. **One consent for the missing packages.** Git, Node.js, tmux and (on Linux) the build
+   toolchain are installed after a single yes, and sudo asks for your password once for
+   the whole run. Nothing is installed silently. If no agent CLI is found, a menu offers
+   to install any of them (DeepSeek excepted: its npm package installs only a launcher
+   with no runnable profile), or you skip and install one yourself later.
+2. **How the dashboard should be reachable.** Three choices:
+   - **Tailscale** (recommended for phone access): keeps the loopback bind, installs
+     Tailscale if needed, logs in, enables the tailnet HTTPS toggle (it opens the admin
+     page for you and waits; Ctrl+C there skips Tailscale for this run), then configures `tailscale serve` after the build and
+     verifies the result end to end. If another app already owns `:443` on your node,
+     you choose between a sub-path (`https://<machine>.<tailnet>.ts.net/codeman`, the
+     default), a second port, replacing the other mapping, or skipping.
+   - **Your local network** (`0.0.0.0`): prompts for a password. Skipping the password takes
+     an explicit confirmation and ends on a loud warning.
+   - **This machine only** (`127.0.0.1`): the safest option, and the default for a bare
+     `codeman web` regardless of what you pick here.
+
+   Which one is preselected depends on what the installer finds. A fresh install defaults to
+   the local network, unless Tailscale is already connected, in which case it defaults to
+   Tailscale. An existing loopback install defaults to keeping loopback, or to Tailscale when
+   a serve mapping for Codeman is already there. A bare Enter never pulls in new software,
+   and a non-interactive run always keeps the safe loopback default.
+3. **What to call this machine on your tailnet** (Tailscale route only). By default the URL
+   uses the machine's existing name. Answer yes to rename it `codeman-<hostname>`; the
+   default is no, because the tailnet name is also what SSH and everything else on that
+   machine are reached by.
+4. **Whether to run Codeman in the background.** Enter installs a systemd user service or a
+   macOS LaunchAgent that starts on boot; answering no offers to start it in this terminal
+   instead, or not at all.
+
+It ends on a screen with the URL (your tailnet, your network, or this machine), a QR code to
+scan with your phone, and the two commands you need to manage the service.
+
+Re-running the same one-liner **updates an existing install in place**. Local changes in
+`~/.codeman/app` are stashed rather than discarded, a running service is restarted and
+verified, and your existing network binding is preserved. An interrupted first install
+resumes instead of restarting.
+
+Other entry points:
+
+```bash
+install.sh status       # print the URLs, the QR code and the manage commands again
+install.sh update       # update only
+install.sh uninstall    # remove (offers to undo a rename it performed)
+install.sh tailscale    # retrofit Tailscale access onto an existing install
+install.sh name [<n>]   # rename this machine on your tailnet (default codeman-<hostname>)
+install.sh cloudflared  # install cloudflared for the in-app Cloudflare tunnel
+```
+
+**Flags** answer the questions from the command line and pipe through `bash -s --`:
+
+```bash
+curl -fsSL https://getcodeman.com/install | bash -s -- --tailscale --service
+curl -fsSL https://getcodeman.com/install | bash -s -- --lan --password 'x' --service
+curl -fsSL https://getcodeman.com/install | bash -s -- --local --run
+```
+
+`--tailscale` / `--lan` / `--local` answer the access question, `--name <n>` / `--no-rename`
+the name, `--service` / `--run` / `--no-start` the last one. `--yes` takes every default
+(it still waits on a Tailscale login URL, and a network bind still asks for a password).
+`--port <n>` moves Codeman off 3000; the service file and the serve mapping follow it. On an
+existing install, `--port` and `--password` re-run the setup so the service file picks them up,
+and a re-run with `--lan` or `--tailscale` keeps the password the service already has.
+
+**Automation and CI**: with no terminal attached, any step that would change the system
+aborts with instructions instead of running silently. Set `CODEMAN_NONINTERACTIVE=1` to
+approve those steps. `CODEMAN_TAILSCALE=1` preselects the Tailscale answer, and never
+installs Tailscale itself non-interactively; a non-interactive run never renames the
+machine and never starts a service. Everything the unattended steps print goes to
+`~/.codeman/install.log`, and the last lines of it are shown when a step fails.
+
+## Route B: npm
+
+```bash
+npm install -g aicodeman
+codeman web
+```
+
+The npm package is named `aicodeman`; the product is Codeman. Both `codeman` and
+`aicodeman` are installed as commands.
+
+The trade-off against Route A: no guided network setup, and the in-app self-updater does
+not apply. npm installs report as non-updatable in **App Settings → System → Updates**, and
+you update with `npm update -g aicodeman`.
+
+## Route C: git clone
+
+For contributing, or for running unreleased code.
+
+```bash
+git clone https://github.com/Ark0N/Codeman.git
+cd Codeman
+npm install            # postinstall builds the vendored xterm addon bundles
+npm run dev            # dev server on http://localhost:3000
+```
+
+For a production run from a clone:
+
+```bash
+npm run build
+npm run start
+```
+
+`npm run dev` runs TypeScript directly through `tsx` with no build step. The frontend is
+plain JavaScript served from `src/web/public/` with no bundler, so editing a `.js` or `.css`
+file and reloading the page is enough. The one exception is `index.html`, which is read once
+at server start, so markup changes need a restart.
+
+See [Contributing](Contributing) for the rest of the development loop.
+
+## Route D: Docker Compose
+
+Codeman itself can run in a container and spawn Docker cases as sibling containers through
+the host's Docker socket. Copy `docker/.env.example` to `docker/.env`, set
+`CODEMAN_PASSWORD`, then:
+
+```bash
+bash docker/Start-Codeman.sh
+```
+
+Run the script again after updating rather than a plain `docker compose up`, so the rebuilt
+image, the refreshed volumes and the entrypoint arrive together. The full guide, including
+storage and networking options, is
+[`docker/README.md`](https://github.com/Ark0N/Codeman/blob/master/docker/README.md).
+
+## Installing an agent CLI
+
+Codeman drives CLIs, it does not bundle them. Install at least one:
+
+| CLI             | Install                                                            | Notes                                                                      |
+| --------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| **Claude Code** | `npm i -g @anthropic-ai/claude-code`                               | The primary target. Some Codeman features are Claude-only: see [Agent CLIs](Agent-CLIs). |
+| **OpenCode**    | See [opencode.ai](https://opencode.ai)                             |                                                                            |
+| **Codex**       | See [developers.openai.com/codex/cli](https://developers.openai.com/codex/cli) |                                                                |
+| **Antigravity** | See [antigravity.google](https://antigravity.google)               | Google's successor to the consumer Gemini CLI.                             |
+| **Gemini CLI**  | See [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) | Enterprise only since Google's June 2026 consumer cutover.  |
+| **Pi**          | See [pi.dev](https://pi.dev)                                       | No permission prompts and no sandbox by design. Read [Agent CLIs](Agent-CLIs) before using it on a repo you care about. |
+| **Grok Build**  | `curl -fsSL https://x.ai/cli/install.sh \| bash`                   | xAI. Lands in `~/.grok/bin`; `grok login --device-auth` for headless hosts.  |
+| **DeepSeek Harness** | `npm i -g @deepseek-ai/dsh pnpm`, then a terminal profile      | The npm package is only a launcher. Codeman's Run menu installs the community terminal profile for you. See [Agent CLIs](Agent-CLIs). |
+| **OMP**         | `curl -fsSL https://omp.sh/install \| sh`                          | Oh My Pi. Run it once by hand to finish its own onboarding.                |
+
+Log each CLI in once, by hand, before pointing Codeman at it. Codeman never collects or
+stores your CLI credentials.
+
+## Verify the install
+
+```bash
+codeman doctor          # checks Node, tmux, the agent CLIs, document converters
+codeman --version
+codeman web             # then open http://localhost:3000
+```
+
+`codeman doctor --json` gives machine-readable output, and `--category core` narrows it to
+the things a session cannot start without.
+
+If the dashboard loads and **+ New Session** opens, you are done. Continue to
+[Quick Start](Quick-Start).
+
+## Where things live
+
+| Path                    | What                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------ |
+| `~/.codeman/app`        | The installed code (installer route only).                                                        |
+| `~/.codeman/`           | All state: `state.json`, settings, session history, push keys, TLS certs. See [Core Concepts](Core-Concepts). |
+| `~/codeman-cases/`      | Cases created from scratch. Linked cases stay wherever they already are.                          |
+| `~/.codeman/web.log`    | Log for a detached (`-d`) server.                                                                 |
+
+Everything is under your home directory, and nothing needs root.
+
+## Keeping it running
+
+A bare `codeman web` dies with the shell that started it. Two ways to outlive that:
+
+```bash
+codeman web -d          # detached; --status and --stop manage it
+codeman service install # systemd user unit or macOS LaunchAgent; survives reboots
+```
+
+Full detail, including logs and the self-updater, is in
+[Running As A Service](Running-As-A-Service).
+
+## Updating
+
+| Install route | How to update                                                     |
+| ------------- | ----------------------------------------------------------------- |
+| Installer     | Re-run the one-liner, or **App Settings → System → Updates** in the UI. |
+| npm           | `npm update -g aicodeman`                                          |
+| git clone     | `git pull && npm install && npm run build`, then restart.          |
+| Docker Compose | Re-run `Start-Codeman.sh`. The in-app updater works too, and refuses a release that changes the container definition until you re-run the script. |
+
+The in-app updater covers git-clone installs supervised by systemd or launchd. It restarts
+the process that is running it, so the actual work happens in a detached script and the
+browser polls across the restart. Progress appears in the UI.
+
+## Uninstalling
+
+```bash
+install.sh uninstall            # installer route
+npm uninstall -g aicodeman      # npm route
+```
+
+Neither removes `~/.codeman/` or `~/codeman-cases/`. Delete those by hand if you want the
+state and your case folders gone as well, and check `~/codeman-cases/` first: linked cases
+point at directories you already had, but cases created from scratch have their only copy
+there.
+
+Running tmux sessions are not killed by an uninstall. `tmux -L codeman kill-server` ends
+them.
+
+## Windows (WSL)
+
+```powershell
+wsl bash -c "curl -fsSL https://getcodeman.com/install | bash"
+```
+
+Codeman requires tmux, so Windows runs it inside
+[WSL2](https://learn.microsoft.com/en-us/windows/wsl/install). If you do not have WSL yet:
+run `wsl --install` in an admin PowerShell, reboot, open Ubuntu, and install your agent CLI
+*inside* WSL. `http://localhost:3000` then works from your Windows browser.
+
+Work inside the Linux filesystem (`~/project`), not `/mnt/c/...`. Filesystem watching and
+git are both dramatically slower across the Windows mount, and agents notice.
+
+## macOS notes
+
+**`Error: posix_spawnp failed.` on every session start.** node-pty publishes its macOS
+`spawn-helper` without the executable bit, and macOS launches every PTY through it. Codeman
+detects this and repairs it automatically on the first failure. If you hit it on a clone
+install and want to fix it by hand:
+
+```bash
+npm run fix:node-pty
+```
+
+This is a `chmod`, not a rebuild. Look in `prebuilds/darwin-<arch>/`, not
+`build/Release/`, which does not exist on macOS. Linux cannot reproduce this.
+
+**launchd and PATH.** A LaunchAgent gets `/usr/bin:/bin:/usr/sbin:/sbin`, which finds
+neither a Homebrew or nvm `node` nor `tmux` or `claude`. `codeman service install` bakes
+your current PATH into the unit for exactly this reason, so prefer it over a hand-written
+plist.
+
+## Gotchas
+
+- **`tmux: command not found` after a successful install.** The installer asks before
+  installing packages, and a declined prompt is a valid answer it remembers. Install tmux
+  and re-run.
+- **Port 3000 in use.** `codeman web --port 8080`, or set `CODEMAN_PORT`.
+- **Two Codemans on one machine.** The data directory and the tmux socket are both process
+  wide, so a second instance discovers and attaches the first one's live sessions. Give each
+  a distinct `CODEMAN_INSTANCE` before starting a second. See [Core Concepts](Core-Concepts).
+- **The dashboard is not reachable from your phone.** That is the default, not a fault. The
+  server binds `127.0.0.1`. See [Remote Access](Remote-Access).
+
+## Read next
+
+- [Quick Start](Quick-Start) - your first working session.
+- [Agent CLIs](Agent-CLIs) - picking and setting up a run mode.
+- [Remote Access](Remote-Access) - reaching it from another device.
+- [Troubleshooting](Troubleshooting) - when the above did not go as written.

docs/wiki/Keeping-Agents-Running.md

@@ -0,0 +1,167 @@
+# Keeping Agents Running
+
+Codeman exists for the hours you are not at the keyboard. This page covers how it notices an
+agent has stopped, what it does about it, and how to run a session overnight without
+babysitting it.
+
+Everything here is **per session and off by default**. A session you never configure just
+sits there when it finishes, which is usually what you want.
+
+## How Codeman knows an agent is idle
+
+Harder than it sounds, and worth understanding, because it is what every other feature here
+is built on.
+
+**For Claude sessions**, the naive signal does not work. Claude redraws its prompt marker
+roughly once a second all the way through a turn, so "saw a prompt, waited two seconds,
+called it idle" flipped working sessions to idle a couple of seconds into every turn. Its
+real working indicator is an animated line whose glyph and wording both change, and terminal
+repaints arrive in partial fragments, so matching it in the output stream does not work
+either.
+
+So Codeman waits for the pane to go quiet, then **asks the screen** what is on it before
+believing the session is idle. Turn-start detection works the same way in reverse: a
+sustained run of repaints marks a turn as started, with the same screen check vetoing mere
+keystroke echo. Idle now lands a few seconds after a turn genuinely ends.
+
+There are several layers stacked on that: a completion message from the CLI, an AI check,
+output silence, and token stability.
+
+**For the other CLIs** it depends on what the CLI tells Codeman. Codex declares its own
+prompt glyph and working line, so it gets the same screen check Claude does (before 1.26.1
+every Codex session reported idle for its whole life). DeepSeek Harness reports idle,
+working and blocked to Codeman itself, which is as precise as hooks. Everything else is
+output stabilization: the session is idle when output stops changing. Coarser, and it is
+why the features further down this page are Claude-only.
+
+## The Respawn Controller
+
+Respawn keeps a session working past the point where the agent would otherwise stop. When
+the session goes idle, Codeman runs a cycle and starts it again.
+
+A cycle is up to four steps, each optional:
+
+1. **Update prompt.** Ask the agent to write down where it got to, so the next round can pick
+   it up.
+2. **`/clear`.** Reset the context window.
+3. **`/init`.** Re-read the project's `CLAUDE.md`.
+4. **Kickstart prompt.** Tell it to continue.
+
+Steps 2 and 3 are what make long runs possible: without a context reset, a multi-hour
+session eventually spends its whole window on its own history.
+
+Configure it in **Session Options → Respawn**, then press **Enable**. It repeats until the
+duration you set runs out.
+
+| Setting                | What it controls                                                        |
+| ---------------------- | ----------------------------------------------------------------------- |
+| **Idle timeout**       | How long the session must be quiet before a cycle starts.                |
+| **Duration**           | How long the whole arrangement stays armed.                              |
+| **Inter-step delay**   | Pause between the steps above, so a step is not sent into a busy pane.    |
+| **`/clear` + `/init`** | Whether the context reset happens at all.                                |
+| **Update prompt**      | What the agent is asked to record before the reset.                      |
+| **Kickstart prompt**   | What starts the next round.                                              |
+| **Auto-accept prompts**| Answer routine confirmation dialogs automatically.                        |
+
+### Presets
+
+Five built-ins, and the numbers matter more than the names. The idle timeout is the main
+difference: a lead session coordinating subagents is legitimately silent for a minute at a
+time, and a three second timeout would interrupt it constantly.
+
+| Preset         | Idle timeout | Duration | Built for                                                       |
+| -------------- | ------------ | -------- | --------------------------------------------------------------- |
+| **Solo**       | 3s           | 60 min   | One agent working alone, fast cycles with a context reset.       |
+| **Subagents**  | 45s          | 240 min  | A lead session running Task subagents; tolerates their silences. |
+| **Team**       | 90s          | 480 min  | Leading an agent team; tolerates long silences.                  |
+| **Ralph/Todo** | 8s           | 480 min  | Working through a task list with progress tracking.              |
+| **Overnight**  | 10s          | 480 min  | Unattended overnight runs with a full reset between cycles.      |
+
+Start from the preset that matches your shape of work and adjust the idle timeout first.
+Presets you build yourself can be saved alongside these.
+
+### What it costs
+
+Every cycle is real tokens: the update prompt, the reset, and the kickstart, plus whatever
+work follows. An overnight run is a deliberate spend, not a background nicety. The duration
+setting is the ceiling, and it is worth setting honestly.
+
+## Auto-resume when a usage limit resets
+
+**Claude only.** At the top of the Respawn tab.
+
+When Claude halts on a subscription limit, the message names the time the limit resets.
+Codeman parses it, arms a timer for two minutes after that, then sends Escape followed by
+`continue`.
+
+The important part is what it does **not** do: respawn cycles are blocked while a session is
+limit-paused. Without that, the next cycle would fire `/clear` and wipe the conversation you
+are waiting to resume. This is the single most useful setting for overnight runs on a
+subscription plan.
+
+## The plan usage chip
+
+**Claude only.** A header chip showing live subscription usage, on by default on desktop and
+off on phones.
+
+It works through a status line exporter that Codeman hands to `claude` as an ephemeral
+setting when it spawns the session, never written to disk, which posts Claude's own rate
+limit data back to Codeman. Your own status line (project-local, project, then
+`~/.claude/settings.json`) is wrapped and printed through, and a `claude` you run by hand
+outside Codeman sees nothing of it. Workspaces an older Codeman wrote the exporter into are
+cleaned up the first time a session starts there. Codex limits come from a read-only poll of
+its own app-server. Known limit: sessions inside a Docker case do not feed the chip yet.
+
+The chip and the exporter are the same setting. Turning the chip on without the exporter
+would leave it showing a dash forever, so resolve it in one place: **App Settings**. A
+device writes the switch only when it flips the chip, so a phone (chip off by default)
+saving its font size cannot switch collection off for your desktop.
+
+## Circuit breakers
+
+Two, and they are unrelated:
+
+- **The Ralph breaker** stops respawn thrashing. It moves from closed to half-open to open,
+  and is reset from the session's Ralph controls.
+- **The PTY-exit breaker** trips when a session's process exits repeatedly and quickly, and
+  blocks automatic restarts so a broken configuration cannot spin forever.
+
+The PTY-exit breaker resets **only** on an explicit clear. Reattaching to the session does
+not clear it, deliberately, so a UI reconnect cannot paper over a session that is genuinely
+failing to start.
+
+## A working overnight setup
+
+1. Start a Claude session in the case you want worked on.
+2. Give it a clear goal and let it start. Respawn continues work, it does not invent it.
+3. **Session Options → Respawn → Overnight preset.**
+4. Turn on **auto-resume on usage limit**.
+5. Set the duration to how long you actually want it running.
+6. Press **Enable**.
+7. Optionally turn on push notifications so a blocking question reaches your phone: see
+   [Notifications And Approvals](Notifications-And-Approvals).
+
+In the morning, the **Away Digest** summarizes what happened while you were gone, and the
+run summary and lifecycle log carry the detail.
+
+## Gotchas
+
+- **Respawn without a context reset stalls eventually.** The window fills with history and
+  the agent gets less useful every cycle.
+- **An idle timeout that is too short interrupts real work.** If the agent runs long tool
+  calls or coordinates subagents, raise it. That is what the Subagents and Team presets are.
+- **The update prompt is what makes a reset survivable.** After `/clear`, everything the
+  agent knows comes from that summary and the project files. A vague update prompt produces
+  a vague next cycle.
+- **Non-Claude sessions can respawn**, but with output-based idle detection and no
+  usage-limit auto-resume.
+- **Do not run respawn on a session you are actively typing in.** It will send prompts
+  underneath you.
+
+## Read next
+
+- [Autonomous Loops](Autonomous-Loops) - Ralph and the orchestrator, for structured
+  autonomous work rather than "keep going".
+- [Cron Jobs](Cron-Jobs) - starting work on a schedule instead of continuing it.
+- [Notifications And Approvals](Notifications-And-Approvals) - being told when it needs you.
+- [`docs/respawn-state-machine.md`](https://github.com/Ark0N/Codeman/blob/master/docs/respawn-state-machine.md) - the state machine itself.

docs/wiki/Keyboard-Shortcuts.md

@@ -0,0 +1,78 @@
+# Keyboard Shortcuts
+
+Every binding, and how to change them. `Ctrl` also accepts `Cmd` on macOS.
+
+Press `Ctrl+?` in the app for the same list in a floating overlay.
+
+## Sessions and tabs
+
+| Shortcut                        | Action                                                          |
+| ------------------------------- | --------------------------------------------------------------- |
+| `Ctrl+K` (also `Cmd+K`, `Alt+K`)| Find an open session or start a new one.                         |
+| `Ctrl+W`                        | Kill the active session.                                         |
+| `Ctrl+Tab`                      | Next session.                                                    |
+| `Alt+[` / `Alt+]`               | Previous / next tab.                                             |
+| `Alt+1` to `Alt+9`              | Switch to tab N. Physical keys, so macOS Option layouts work.    |
+| `Ctrl+Shift+{` / `Ctrl+Shift+}` | Move the active tab left / right.                                |
+| `Alt+B`                         | Collapse / expand the session sidebar, when that layout is on.    |
+
+## Terminal
+
+| Shortcut                | Action                                                          |
+| ----------------------- | --------------------------------------------------------------- |
+| `Enter`                 | Send.                                                            |
+| `Shift+Enter`           | Insert a newline without sending.                                |
+| `Ctrl+Enter`            | Same.                                                            |
+| `Ctrl+C`                | Copy the selection, or interrupt when nothing is selected.       |
+| `Ctrl+Shift+C`          | Copy the selection. Never interrupts.                            |
+| `Ctrl+V`                | Paste. An image on the clipboard uploads and pastes its file path instead. |
+| `Ctrl+L`                | Clear the terminal.                                              |
+| `Ctrl+Shift+R`          | Restore terminal size.                                           |
+| `Ctrl` `+` / `Ctrl` `-` | Font size.                                                       |
+| `Shift+Wheel`           | Scroll the local buffer, even where the wheel is forwarded to the CLI. |
+| `Shift+drag`            | Start a selection in a pane whose mouse events go to the CLI.    |
+| Right-click             | Copy the selection. With nothing selected the native menu is left alone. |
+| `Ctrl+Z`                | Swallowed in agent sessions so a running CLI cannot be suspended. Normal job control in a shell. |
+
+Anything you copy is cleaned on the way to the clipboard: each line loses the padding spaces a full-screen program paints across the rest of the row. Leading indentation is left exactly as it is, so indented code, a `git log` message body and `git diff` context lines paste back the way they looked on screen. An `Alt+drag` rectangular selection is copied exactly as it looks, so its columns stay lined up.
+
+## Everything else
+
+| Shortcut       | Action                          |
+| -------------- | ------------------------------- |
+| `Ctrl+Shift+V` | Toggle voice input.              |
+| `Ctrl+?`       | Shortcut reference overlay.      |
+| `Escape`       | Close panels and modals.         |
+
+## Rebinding
+
+**App Settings → Shortcuts.** Bindings live in a registry with per-user overrides, so a
+rebind is stored as an override on top of the default rather than replacing the table.
+
+Two things are deliberately not rebindable:
+
+- **`Ctrl+C` smart copy.** The generic dispatch loop calls `preventDefault()` on every
+  shortcut it handles, and doing that to `Ctrl+C` would swallow the interrupt when nothing
+  is selected. It is handled separately for that reason.
+- **`Escape`**, which closes whatever is open.
+
+## Why some chords behave oddly
+
+The terminal sees keystrokes before the app does. Any chord the app claims has to also be
+swallowed at the terminal layer, or xterm writes the control byte into the session as well
+as triggering the action. If you rebind something to a chord the terminal cares about
+(`Ctrl+D`, say), expect the CLI to see it too.
+
+`Alt+1` through `Alt+9` are matched on **physical key position** rather than the character
+produced, so macOS Option layouts that produce `¡™£` still switch tabs.
+
+## On phones
+
+There is no physical keyboard, so the equivalents live in the keyboard accessory bar: `Esc`,
+`Ctrl` as a one-shot modifier, `Tab`, arrows, and quick actions. See
+[Mobile Guide](Mobile-Guide).
+
+## Read next
+
+- [The Dashboard](The-Dashboard) - what the shortcuts are navigating.
+- [Settings Reference](Settings-Reference) - where the overrides are stored.

docs/wiki/Mobile-Guide.md

@@ -0,0 +1,177 @@
+# Mobile Guide
+
+Codeman on a phone is not a shrunken desktop UI. It is the surface most of its design
+attention has gone into, because checking on an agent from a bus is the thing this software
+is for.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Ark0N/Codeman/master/docs/screenshots/mobile-session-keyboard-20260727.png" alt="Answering an agent prompt on a phone" width="300">
+</p>
+
+## Getting there
+
+1. **Set up access.** Tailscale is the recommended route and gives you real HTTPS. See
+   [Remote Access](Remote-Access).
+2. **Log in by QR.** Open the dashboard on your desktop and scan the code. No password
+   typing. Tokens are single use and rotate every 60 seconds.
+3. **Install it to your home screen.** On iOS this is mandatory for push notifications;
+   Safari does not deliver push to tabs. On Android it makes the app full screen.
+
+HTTPS matters for more than security here: microphone access and push notifications both
+require a secure context.
+
+## The layout
+
+| Element              | Where                                                                 |
+| -------------------- | --------------------------------------------------------------------- |
+| Header               | Fixed at the top, deliberately minimal. Desktop-only controls never appear. |
+| Tab strip            | Scrolls horizontally. The active tab is always scrolled into view.      |
+| Terminal             | The rest of the screen.                                                |
+| Toolbar              | Bottom: Run, Stop, **Enter**, case picker, voice, settings.             |
+| Keyboard bar         | Above the on-screen keyboard when it is open.                           |
+
+The phone layout applies up to 599px of viewport width, so the Plus and Pro Max iPhones,
+the Pixel Pro and a folded Z Fold get it too; wider devices get the tablet layout. Layout
+respects notch and home-indicator safe areas, touch targets are 44px, and the case picker is
+a bottom sheet rather than a dropdown. On a folding phone (iPhone Duo) dialogs stay clear of
+the hinge, and opening or closing the device is treated as the device changing shape, never
+as the keyboard appearing.
+
+**Swipe left and right** on the terminal to switch sessions.
+
+## The home screen
+
+Tapping the "C" logo gives a session overview rather than a welcome page:
+
+1. **NEEDS YOU** first: sessions blocked on a question, with answer strips so you can
+   resolve them without opening the session.
+2. **CURRENT SESSIONS** with live status.
+3. **PAST SESSIONS**, resumable.
+
+Row status uses the same language as the tabs: green when fine, pulsing while working,
+yellow when waiting for input, red when a question is pending.
+
+The split Run button carries the same per-backend colours as the desktop toolbar, and its
+picker mirrors the desktop run-mode menu.
+
+On by default; it can be turned off in settings.
+
+## The keyboard accessory bar
+
+A row of keys above the virtual keyboard, and what it contains depends on the session.
+
+**Agent sessions** get quick actions: `/init`, `/clear`, `/compact`, a Compose key, `Esc`,
+a path picker, and 🧠 when Read My Mind is on. Compose opens a multiline editor with
+autocorrect: Enter adds a new line, and only Send delivers the text, as one paste followed
+by Enter, so your line breaks reach the agent intact. Anything already typed on the terminal
+prompt moves into the editor when it opens. Drafts are kept per session and in memory only,
+so switching tabs keeps them and a page reload forgets them; a dot on the key shows a draft
+is parked. The editor's Image button attaches photos and puts their paths into the draft.
+Destructive commands need a double press, so you cannot fire `/clear` with a stray thumb. On
+Codex sessions the bar also shows `⇧←` and `⇧→`, the Shift-modified arrows Codex binds to
+editing the last queued message and walking the prompt stack.
+
+**Shell sessions** automatically swap it for terminal controls: `Ctrl`, `Esc`, `Tab`, four
+arrows, a direct Paste key (shell input is not an agent prompt, so there is no Compose
+there), and dismiss. Your normal preference is remembered and restored when you
+switch back to an agent session, so a settings change during a shell session cannot strip
+the bar away permanently.
+
+### One-shot Ctrl
+
+`Ctrl` on the shell bar is a **one-shot modifier**: tap `Ctrl`, then tap `c`, and the
+control byte is sent. It disarms on use, on a second tap, on any other accessory key, on a
+session switch, and when the keyboard closes.
+
+That list matters. A modifier left armed turns your next innocent keystroke into a control
+byte, so it is deliberately eager to disarm. Keys with no control equivalent pass through
+unchanged, exactly like a hardware keyboard.
+
+## The Enter button
+
+The toolbar's dedicated **Enter** button exists because of local echo. On a phone, the
+characters you type are painted locally and have not reached the agent yet; Enter flushes
+them and then submits.
+
+It replays the keypress through the terminal rather than sending a bare carriage return.
+Sending a bare `\r` would submit an empty line and strand your typed text on screen, which
+looks exactly like a dead button.
+
+On phones this button replaces the desktop's **Run Shell** control; starting a shell moved
+into the Run dropdown.
+
+## Tapping, links and copying
+
+- **Tap a link** in terminal output and it opens in a new tab. Same for a link in an agent's
+  answer in the response viewer — it opens a tab rather than navigating the dashboard away,
+  which on a phone would unload the whole session view.
+- **Tap a file path** an agent printed and the file-preview overlay opens; a log path opens the
+  log viewer. Works in scrolled-up transcript too.
+- A tap on the prose *beside* a link still places the cursor as usual, and a tap on a dialog's
+  numbered choice still answers the dialog even when the row contains a path — the dialog wins,
+  because on a phone it is the only interaction that matters.
+- **Long-press to select text**, then drag, or tap the other end to extend the selection — no
+  hairline handles to grab. A small bar offers **Copy**, **Line** (the whole logical line,
+  wrapped rows included) and dismiss. Copy works on plain-HTTP installs too, where the browser
+  clipboard API is unavailable.
+- A swipe is never mistaken for a long-press, and the keyboard stays down while you select.
+
+## Scrolling and the keyboard
+
+- The terminal and toolbar shift up when the keyboard opens, tracked through the browser's
+  visual viewport rather than guessed.
+- **Two ways to dismiss the keyboard**: tap outside the terminal on inert space, or tap twice
+  on inert terminal content. Tapping a control never dismisses it, and tapping the prompt row
+  keeps focus so you can place the caret.
+- A scroll is never mistaken for a tap: travel is measured from the start of the gesture, and
+  multi-touch never counts.
+- **A long prompt stays visible.** Once what you are typing wraps past the last visible row it
+  grows upward over the transcript instead of sliding under the keyboard, so the end of the
+  sentence — where the cursor is — is always on screen. A prompt taller than the visible strip
+  shows its tail.
+
+## Voice
+
+The microphone button, or the keyboard bar. Providers and setup are covered in
+[Input And Voice](Input-And-Voice). Dictating is often faster than typing a prompt on a
+phone, and it is the main reason the feature exists.
+
+## Notifications
+
+Push notifications reach you with no tab open, and with the Approvals Inbox on they carry
+**Approve** and **Deny** buttons handled by the service worker, so you can unblock an agent
+from the lock screen.
+
+Setup in [Notifications And Approvals](Notifications-And-Approvals).
+
+## Reading long answers
+
+The terminal viewport is small. **Last Response** (opt-in header button) renders the agent's
+last answer as scrollable text instead, with a **More** button for additional context.
+
+The [File Viewer](Working-With-Files) works on phones too, including edit mode, which is
+enough to fix a typo an agent introduced while you are away from your desk.
+
+## What is deliberately not on phones
+
+- Extra header buttons. New header controls are kept off phones by policy, with a test that
+  enforces it.
+- The Approvals bell. Phones get the NEEDS YOU strips on the home screen instead.
+- The desktop home tab rail, which needs a wide window.
+- Lineage arcs, which are a desktop overlay.
+
+## Gotchas
+
+- **Typed text sitting on screen has not been sent.** Press Enter.
+- **iOS needs the home screen install for push**, not just a bookmark.
+- **iOS Safari can serve stale JavaScript after an update** until the tab is fully closed.
+  Close it and reopen.
+- **Plain HTTP over a LAN address disables voice and push.** Use HTTPS.
+- **An armed `Ctrl` is visibly highlighted.** If it looks the same as a resting key, you are
+  on an old version, on a light skin.
+
+## Read next
+
+- [Remote Access](Remote-Access) - getting the phone connected in the first place.
+- [Notifications And Approvals](Notifications-And-Approvals) - being told when you are needed.
+- [Input And Voice](Input-And-Voice) - local echo, dictation, and the input rules.

docs/wiki/Multi-User-Mode.md

@@ -0,0 +1,97 @@
+# Multi-User Mode
+
+Share one Codeman with a small trusted team. Each person gets their own login and workspace,
+and sessions, cases, search, and live events are scoped to their owner.
+
+**Off by default.** Without the flag, behaviour is identical to single-user Codeman, because
+every scoping check short-circuits.
+
+## Read this before enabling it
+
+**Multi-user mode separates workspaces. It does not sandbox users from each other.**
+
+Every session still runs as the **same operating system account**. A determined user's agent
+can reach another user's files, because at the OS level they are the same user. This is a
+convenience and organization feature, not a security boundary.
+
+If you need real isolation:
+
+- Pair each user with [Docker Cases](Docker-Cases), which gives their work its own
+  filesystem and network.
+- Or run separate Codeman instances under separate OS accounts, each with its own
+  `CODEMAN_INSTANCE`.
+
+"Small trusted team" is the honest description of who this is for.
+
+## Enabling it
+
+```bash
+codeman users add alice --admin      # create the first admin, prompts for a password
+codeman web --multiuser              # or CODEMAN_MULTIUSER=1
+```
+
+Then manage users from the CLI or the **Users** entry in App Settings:
+
+```bash
+codeman users add bob                # a regular user
+codeman users list
+codeman users passwd bob             # reset to a one-time password
+codeman users rm bob
+```
+
+`--password-stdin` reads the password from standard input, for scripts.
+
+Accounts live in `~/.codeman/users.json` with scrypt-hashed passwords, mode 0600.
+Administrative actions are audited to `~/.codeman/admin-audit.jsonl`.
+
+## What each user gets
+
+| Thing               | Scope                                                                        |
+| ------------------- | ---------------------------------------------------------------------------- |
+| **Case space**      | `~/codeman-users/<name>/cases`, their own.                                    |
+| **Sessions**        | Only theirs are listed, reachable, or controllable.                           |
+| **Events**          | Live event routing is per owner, and fails closed.                            |
+| **Search**          | Scoped on read, including historical results.                                 |
+| **File previews**   | Scoped to sessions they own.                                                  |
+| **Path picker**     | Only their own user space as a root, not the whole home directory.            |
+
+Admins see everything.
+
+Ownership threads through every list endpoint, the session lookup helper, the WebSocket
+layer, and file previews. A user cannot address another user's session even by id.
+
+## Safer defaults for regular users
+
+Non-admins get tighter defaults, and lifting them is an explicit per-user grant:
+
+| Default                            | Meaning                                                                  |
+| ---------------------------------- | ------------------------------------------------------------------------ |
+| Claude runs in `auto` permission mode | Anthropic's classifier-guarded mode instead of skip-prompts.           |
+| Raw shell sessions require a grant  | A plain shell is unmediated machine access.                              |
+| Skip-permissions requires a grant   | Same reasoning.                                                          |
+| Cron `launchCommand` requires a grant | It is an arbitrary command on a schedule.                              |
+| Pi project trust defaults to off    | Trust makes Pi execute repo-local TypeScript.                            |
+
+These exist because the OS boundary is shared. They narrow what a normal account can do
+casually; they do not make the account a sandbox.
+
+## Accounts and sessions
+
+Each user authenticates with their own name and password rather than the shared
+`CODEMAN_PASSWORD`. Logins are individually revocable: disable, reset, or delete an account
+at any time, and existing browser sessions can be revoked.
+
+## Gotchas
+
+- **Enabling it does not migrate existing cases** into a user space. They stay where they
+  are, owned by whoever the ownership rules resolve them to.
+- **Admins see everything**, including other users' sessions. Choose admins accordingly.
+- **The audit log is append-only and local.** Ship it somewhere if you care about it.
+- **It is not a substitute for OS accounts.** Restating this because it is the one thing
+  people get wrong.
+
+## Read next
+
+- [Security](Security) - where this fits in the model, and what it does not cover.
+- [Docker Cases](Docker-Cases) - the isolation story that actually isolates.
+- [`docs/multi-user-plan.md`](https://github.com/Ark0N/Codeman/blob/master/docs/multi-user-plan.md) - the design.

docs/wiki/Notifications-And-Approvals.md

@@ -0,0 +1,177 @@
+# Notifications and Approvals
+
+An agent that stops to ask a question, with nobody watching, is a run that quietly wasted an
+hour. This page covers every way Codeman tells you it needs you, and how to answer without
+opening the session.
+
+## The signals, cheapest first
+
+| Surface                | Reaches you                                       | Default |
+| ---------------------- | ------------------------------------------------- | ------- |
+| Tab alert              | While the dashboard is open                        | On      |
+| Browser title flash    | Another tab in the same browser                    | On      |
+| Desktop notification   | Another window on the same machine                 | Opt-in  |
+| Push notification      | Anywhere, even with no tab open                    | Opt-in  |
+| Approvals Inbox        | One queue across every session                     | Opt-in  |
+| Phone overview         | Phone home screen, NEEDS YOU section               | On      |
+| Away Digest            | Afterwards, as a summary                           | Opt-in  |
+
+## Tab alerts
+
+The tab itself changes state:
+
+| State                | Meaning                                                    |
+| -------------------- | ---------------------------------------------------------- |
+| Yellow, blinking     | The agent is waiting for input from you.                    |
+| Red, blinking        | A question or permission prompt is blocking the session.    |
+
+These are a steady colour with a pulse layered on top, not a blink to transparent, so a tab
+needing attention looks that way at every point in the cycle.
+
+They survive a reload. The alert state is re-seeded from the server on page load, so
+reloading the dashboard while a permission dialog is blocking a session does not leave you
+with a normal-looking tab.
+
+For Claude sessions, these come from Claude Code's hooks and are precise about *why* the
+session stopped; DeepSeek Harness sessions report the same states themselves. For the other
+CLIs there are no hooks, so you get the coarser output-based signal.
+
+## Window title and OS notifications
+
+The browser tab title is prefixed `codeman:<host>`, so several Codeman instances across
+several machines stay distinguishable at a glance. Override the hostname with
+`codeman web --title-hostname <name>`.
+
+Desktop notifications use the same prefix. Enable them in **App Settings → Notifications**.
+
+## Push notifications
+
+Push reaches your phone with **no Codeman tab open at all**, which is the only option that
+works while you are actually away.
+
+Setup:
+
+1. Open Codeman over **HTTPS**. Web push requires a secure context. Tailscale gives you real
+   HTTPS; `--https` gives you a self-signed certificate; plain HTTP over a LAN address will
+   not work.
+2. **App Settings → Notifications → Subscribe**, and accept the browser prompt.
+3. On **iOS**, add Codeman to your home screen first. Safari only delivers web push to
+   installed web apps, not to tabs.
+
+Once subscribed, a blocking prompt reaches your phone even from a locked screen.
+
+## The Approvals Inbox
+
+**Opt-in, off by default. Claude sessions, plus DeepSeek Harness sessions, whose terminal
+front door reports its prompts to Codeman.**
+
+One queue of every prompt currently waiting on a human, across all your sessions, answerable
+in place. When you have eight workers running, this is the difference between checking eight
+tabs and checking one list.
+
+Turn it on in **App Settings**. Surfaces:
+
+- **A header bell** with a count, hidden entirely while the count is zero. Never shown on
+  phones.
+- **A drawer** listing each waiting card.
+- **NEEDS YOU strips** at the top of the phone overview home screen.
+
+Each card shows the session, the case, and the captured prompt with its options. Answering
+sends the keystroke into the session for you: a digit for a menu choice, Escape to decline,
+or free text for an idle prompt.
+
+Behaviour worth knowing:
+
+- **One item per session.** A newer prompt supersedes the older one, because the older one
+  is no longer on screen.
+- **Menu answers are validated against the live screen.** Codeman re-captures the pane before
+  sending, and refuses with a conflict if the dialog is no longer there. Otherwise your
+  keystroke would land in the composer as stray text.
+- **Permission and question items clear only on definitive signals**: the turn ending, the
+  dialog completing, an answer, a supersede, the session exiting, or a 12 hour timeout. They
+  do not clear on a heuristic "looks busy again" signal, because that signal is wrong often
+  enough to lose a real prompt.
+- **In memory only.** Restarting the server clears the queue; the prompts themselves are
+  still sitting in the sessions.
+
+### Approve and Deny from the notification
+
+With the inbox enabled, push notifications carry **Approve** and **Deny** buttons. Those are
+handled by the service worker directly, so they work with no tab open: tap Approve on a
+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.
+
+An agent waiting for your comments on an artifact it published never counts as watching.
+Claude shows that as "1 Artifact comment monitor", but the agent hears nothing until you
+comment, so the session alerts you like any other quiet session.
+
+## The phone overview
+
+On phones, tapping the "C" logo gives a session overview with **NEEDS YOU** first, then
+current sessions, then past ones. Rows use the same language as the tab strip: a green dot
+when fine, pulsing while working, yellow when waiting for input, red when a question is
+pending.
+
+Answer strips let you resolve a prompt straight from the home screen without opening the
+session.
+
+## The Away Digest
+
+Retrospective rather than live: what happened while you were gone, aggregated from the
+lifecycle log, run summaries, live sessions, token statistics, and recent subagents.
+
+It is the morning-after view for an overnight run. Enable its header button in
+**App Settings → Header & Panels**.
+
+## Recommended setup for unattended runs
+
+1. HTTPS access, ideally Tailscale. See [Remote Access](Remote-Access).
+2. Push notifications subscribed, with Codeman installed to the home screen on iOS.
+3. Approvals Inbox on.
+4. Auto-resume on usage limit on, for each session you leave running. See
+   [Keeping Agents Running](Keeping-Agents-Running).
+
+That combination means a blocking question wakes your phone and can be answered in two taps
+from the lock screen.
+
+## Gotchas
+
+- **No push over plain HTTP.** It is a browser requirement, not a Codeman one.
+- **iOS needs the home screen install.** A Safari tab will never receive push.
+- **The bell is invisible at zero.** That is deliberate, not a broken setting.
+- **Approvals need real signals.** They are built on hook events, which Claude emits and
+  DeepSeek Harness reports itself; the other CLIs do neither.
+- **A stale menu answer is refused, not sent.** If you answer a card for a dialog that has
+  since gone away, Codeman declines rather than typing a digit into the composer.
+
+## Read next
+
+- [Keeping Agents Running](Keeping-Agents-Running) - what to configure before walking away.
+- [Mobile Guide](Mobile-Guide) - the phone surfaces in full.
+- [Settings Reference](Settings-Reference) - where each of these toggles lives.

docs/wiki/Quick-Start.md

@@ -0,0 +1,156 @@
+# Quick Start
+
+From an installed Codeman to a working agent, in about five minutes. If you have not
+installed yet, start at [Installation](Installation).
+
+## 1. Start the server
+
+```bash
+codeman web
+```
+
+It prints a URL, `http://localhost:3000` by default. Open it.
+
+The server binds `127.0.0.1` only, so this URL works from the machine running it and
+nowhere else. That is deliberate: Codeman starts agents with permission prompts skipped by
+default, so anyone who can reach the dashboard can run code on this machine. Reaching it
+from your phone is a separate, deliberate step covered in [Remote Access](Remote-Access).
+
+To keep it alive after you close the terminal, use `codeman web -d` instead, or install it
+as a service. See [Running As A Service](Running-As-A-Service).
+
+## 2. Meet the welcome screen
+
+With no sessions running you get the welcome screen:
+
+- **Run buttons** for each agent CLI Codeman found on your PATH. If you expected one and it
+  is missing, its binary is not visible to the server; see [Agent CLIs](Agent-CLIs).
+- **A QR code**, if a password is set. Scanning it logs a phone in without typing anything.
+- **Resume Conversation**, a list of past sessions, including Claude conversations started
+  outside Codeman. Empty on a fresh install.
+- **Search**, across sessions, events, and files.
+
+You can click a Run button right now and get a working agent in your current case. The rest
+of this page is the deliberate version.
+
+## 3. Pick or create a case
+
+A **case** is a named working directory that Codeman remembers. Every session runs inside
+one. The case picker is in the bottom toolbar.
+
+To make a new one, click **+** next to the picker. The Add Case dialog has three tabs:
+
+| 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 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
+**1M Opus Context**. Both are off by default and both are safe to ignore for now.
+
+**Create New** also has a checkbox for running the case inside a Docker container, and a
+**Remote** panel for running it over SSH on another machine. Those are
+[Docker Cases](Docker-Cases) and [Remote SSH Sessions](Remote-SSH-Sessions); skip them for
+your first session.
+
+## 4. Pick a run mode and hit Run
+
+The **Run** button starts an agent in the selected case. The arrow next to it picks which
+one:
+
+| Mode                 | What starts                                                    |
+| -------------------- | -------------------------------------------------------------- |
+| **Claude Code**      | The default, and the mode every Codeman feature supports.       |
+| **OpenCode**         |                                                                 |
+| **Codex**            | OpenAI's CLI.                                                   |
+| **Gemini**           | Enterprise only since Google's consumer cutover.                |
+| **Antigravity**      | Google's successor to the consumer Gemini CLI.                  |
+| **Pi**               | No permission prompts and no sandbox by design.                 |
+| **Grok Build**       | xAI's CLI.                                                      |
+| **DeepSeek Harness** | Needs a terminal profile; the menu offers to install one.       |
+| **OMP**              | Oh My Pi, configured entirely through its own `~/.omp`.          |
+| **Terminal / Shell** | A plain shell, no agent. Also the **Run Shell** button.          |
+
+The dropdown also lists any saved dashboard URLs ([Web Tabs](Web-Tabs)) and your recent
+sessions. Those do not change the run mode: Run always means "start an agent".
+
+Click **Run**. A tab appears, and Codeman spawns the CLI on a real PTY inside a tmux
+session and streams it to your browser.
+
+The number spinner beside the button starts several sessions at once, up to 20. Useful for
+fanning the same case out across parallel workers; unnecessary for a first run.
+
+## 5. Talk to the agent
+
+Click into the terminal and type. It is a real terminal (xterm.js over a real PTY), so full
+TUIs render properly and everything the CLI supports works, slash commands included.
+
+| Key                          | Effect                                        |
+| ---------------------------- | --------------------------------------------- |
+| `Enter`                      | Send.                                          |
+| `Shift+Enter` / `Ctrl+Enter` | Newline without sending.                       |
+| `Ctrl+C`                     | Copy if text is selected, otherwise interrupt. |
+| `Ctrl+Shift+V`               | Voice input.                                   |
+
+You can also paste or drag an image straight into the session, and register external files
+as attachments. See [Working With Files](Working-With-Files) and
+[Input And Voice](Input-And-Voice).
+
+Input is delivered **exactly once**, even if your connection drops mid-prompt. A dropped
+link never loses a prompt and never sends it twice.
+
+## 6. Read the tab
+
+The tab tells you what the session is doing without opening it:
+
+| Signal                | Meaning                                                    |
+| --------------------- | ---------------------------------------------------------- |
+| Green dot             | Alive and idle.                                             |
+| Pulsing green dot     | Working on a turn.                                          |
+| Yellow, blinking      | Waiting for you to type something.                          |
+| Red, blinking         | A question or permission prompt is blocking the agent.      |
+
+Full tour in [The Dashboard](The-Dashboard). If you want a phone notification when an agent
+needs you, that is [Notifications And Approvals](Notifications-And-Approvals).
+
+## 7. Leave, and come back
+
+Close the browser tab. Close the laptop. The agent keeps running, because it lives in tmux
+and not in your browser.
+
+Reopen the dashboard and the session is still there with its scrollback intact. First load
+of a session pulls the full tmux scrollback, so you get the history, not just what arrived
+after you reconnected.
+
+This also survives restarting the Codeman server itself. What does not survive is killing
+the tmux server or rebooting the machine.
+
+## 8. Stop things
+
+| To do this                | Do that                                                             |
+| ------------------------- | ------------------------------------------------------------------- |
+| Interrupt the current turn | `Ctrl+C` with nothing selected, or the **Stop** button.            |
+| Close one session          | `Ctrl+W`, or the tab's close control.                              |
+| Stop the server, keep agents | `codeman web --stop`. The tmux sessions stay alive.              |
+| Stop everything            | `tmux -L codeman kill-server`.                                     |
+
+If you are working *inside* a Codeman-managed session (`echo $CODEMAN_MUX` prints `1`),
+never run `tmux kill-session` or `pkill claude` by hand. You will kill the session you are
+sitting in, along with its siblings.
+
+## Where to go next
+
+**Make it run without you.** [Keeping Agents Running](Keeping-Agents-Running) covers idle
+detection, respawn cycling, and auto-resume when a subscription limit resets. That is the
+feature Codeman exists for.
+
+**Get it on your phone.** [Remote Access](Remote-Access), then
+[Mobile Guide](Mobile-Guide).
+
+**Understand what you just used.** [Core Concepts](Core-Concepts) explains cases, sessions,
+run modes, and what state lives where.
+
+**Automate it.** [Cron Jobs](Cron-Jobs) for scheduled work,
+[Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) for agents that spawn and
+supervise other agents.

docs/wiki/Remote-Access.md

@@ -0,0 +1,275 @@
+# Remote Access
+
+Reaching your Codeman from a phone, a laptop on the other side of the house, or a hotel
+network. This is the page to read carefully, because Codeman's dashboard is a
+remote-code-execution surface by design: it starts agents with permission prompts skipped,
+so whoever can reach it can run code on your machine.
+
+## Start from the default
+
+`codeman web` binds `127.0.0.1`. It is reachable from the machine running it and nothing
+else, which is why the no-password default is safe out of the box. Every option below is a
+deliberate step away from that.
+
+Two rules that make the rest of this page simple:
+
+1. **Never expose Codeman on a network without `CODEMAN_PASSWORD`.** Binding a non-loopback
+   host without one starts, but prints a loud warning with the fixes.
+2. **Prefer keeping the loopback bind** and putting an authenticated tunnel in front of it,
+   over binding wide and relying on a password alone.
+
+## Pick an approach
+
+| Approach              | Good for                                              | Cost                                                      |
+| --------------------- | ----------------------------------------------------- | --------------------------------------------------------- |
+| **Tailscale**         | Phone access, permanently. The recommended setup.      | Install Tailscale on both devices.                         |
+| **Cloudflare tunnel** | A public URL, quickly, from anywhere.                  | Public URL, so a password is mandatory.                    |
+| **LAN + password**    | Home network only, no extra software.                  | Every device on your LAN can reach the login page.         |
+| **SSH port forward**  | You already SSH to the box.                            | Manual, per session, terminal-bound.                       |
+
+## Tailscale (recommended)
+
+Your devices join a private network, and Codeman stays bound to loopback. Nothing is
+published to the internet, and you get real HTTPS with a real certificate.
+
+The installer sets this up for you, including installing Tailscale, logging in, enabling
+tailnet HTTPS, and verifying the result end to end. It ends on the URL with a QR code to
+scan. To retrofit it onto an existing install, or to see the URL and QR code again:
+
+```bash
+install.sh tailscale
+install.sh status
+```
+
+By hand:
+
+```bash
+tailscale serve --bg 3000
+tailscale serve status
+```
+
+Then open `https://<machine>.<tailnet>.ts.net` from any device on your tailnet.
+
+### The name in the URL
+
+The URL is the machine's MagicDNS name, so on a machine called `tnode` it is
+`https://tnode.<tailnet>.ts.net`. Three ways to influence that, from least to most work:
+
+| You want                                   | How                                                                                                   |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| The machine's existing name (default)      | Nothing. This is what the installer does unless you say otherwise.                                     |
+| `https://codeman-<hostname>.<tailnet>.ts.net` | Answer yes to the installer's name question, pass `--name codeman-<hostname>`, or run `install.sh name`. This renames the machine tailnet-wide (SSH included), which is why the installer defaults to no. `install.sh uninstall` offers to rename it back. |
+| `https://codeman.<tailnet>.ts.net`         | A [Tailscale Service](https://tailscale.com/docs/features/tailscale-services). Only a **tagged** node can host one (a device signed in with a user account cannot), the service is defined and approved in the admin console, and the feature is in beta. The installer does not set this up; it is a `tailscale serve --service=svc:codeman --https=443 127.0.0.1:3000` on a tagged host once the service exists. |
+
+If `:443` on your node already belongs to another app, the installer offers Codeman under
+`https://<machine>.<tailnet>.ts.net/codeman` (the default, via `tailscale serve --set-path`
+plus Codeman's `--base-url`), on a second port (`https://<machine>.<tailnet>.ts.net:8443`),
+or replacing the other mapping. It never replaces anything without asking.
+
+Notes:
+
+- Keep the loopback bind. `tailscale serve` connects to `127.0.0.1:3000` locally, so
+  binding wider adds exposure and buys nothing.
+- Your tailnet is the authentication boundary. Setting `CODEMAN_PASSWORD` as well is
+  reasonable defence in depth, especially if other people have devices on your tailnet.
+- Codeman's Host-header allowlist already accepts `.ts.net`, so no extra configuration is
+  needed.
+- The installer never resets or rewrites `serve` mappings other than the one pointing at
+  Codeman's port, so unrelated serve configuration is left alone. It also never opens a
+  `tailscale funnel` (that is the public internet) and never advertises a Tailscale Service.
+- On macOS, the App Store and standalone Tailscale apps only run once someone is logged in,
+  so a headless Mac needs the open-source `tailscaled` for the URL to come back after a
+  reboot on its own.
+
+## Cloudflare tunnel
+
+A free [quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)
+gives you a public HTTPS URL with no port forwarding, no DNS, and no static IP:
+
+```
+Browser → Cloudflare edge (HTTPS) → cloudflared → localhost:3000
+```
+
+Prerequisites: [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)
+installed, and `CODEMAN_PASSWORD` set.
+
+```bash
+./scripts/tunnel.sh start     # starts the tunnel, prints the public URL
+./scripts/tunnel.sh url
+./scripts/tunnel.sh status
+./scripts/tunnel.sh stop
+```
+
+The quick-tunnel URL is a random `*.trycloudflare.com` address that changes every time the
+tunnel restarts. For a stable hostname, `./scripts/tunnel.sh named setup` walks through a
+named tunnel.
+
+To survive reboots:
+
+```bash
+systemctl --user enable codeman-tunnel
+loginctl enable-linger $USER
+```
+
+There is also a toggle in **App Settings → System → Remote access**.
+
+**The tunnel refuses to start without a password.** That is on purpose: a public URL with no
+authentication is a terminal on your machine handed to the internet. Acknowledging the risk
+explicitly is possible from the UI toggle, and only from there; the API will not do it for
+you.
+
+## LAN plus password
+
+```bash
+export CODEMAN_PASSWORD='something long'
+codeman web -H 0.0.0.0 --https
+```
+
+Every device on your local network can now reach the login page. `--https` generates a
+self-signed certificate into `~/.codeman/certs/`, which your browser will warn about once.
+
+`CODEMAN_USERNAME` defaults to `admin`.
+
+The installer offers this path and prompts for the password. On re-runs it preserves
+whichever binding you already chose.
+
+## SSH port forward
+
+No configuration at all, if you already have SSH access:
+
+```bash
+ssh -L 3000:localhost:3000 you@your-box
+```
+
+Then open `http://localhost:3000` on the local machine. Codeman keeps its loopback bind and
+sees a local connection. Good for occasional access, awkward as a permanent arrangement
+because it dies with the SSH session.
+
+## Logging in from a phone
+
+Typing a long password on a phone keyboard is miserable, so Codeman issues **single-use QR
+tokens**. The desktop dashboard shows a QR code; scan it and the phone is authenticated.
+
+How it behaves:
+
+- The code rotates every 60 seconds, with a 90 second grace window so scanning during a
+  rotation still works.
+- Each token is **single use**. The moment a phone consumes it, a new one is generated.
+- The URL contains a 6-character lookup code, not the secret, so it does not leak through
+  browser history, `Referer` headers, or the tunnel provider's logs.
+- The desktop shows a toast naming the device and browser that just authenticated, with a
+  one-click revoke.
+- QR attempts are rate limited separately from password attempts, so a mistyped password
+  cannot lock out your QR login and vice versa.
+
+Someone holding only the tunnel URL still meets the normal password prompt. The QR is the
+fast path, not a bypass.
+
+Design detail and the threat analysis it is built against:
+[`docs/qr-auth-plan.md`](https://github.com/Ark0N/Codeman/blob/master/docs/qr-auth-plan.md).
+
+## Behind a reverse proxy
+
+Codeman enforces a Host-header allowlist on every request to block DNS rebinding, and the
+same allowlist gates the cross-site Origin check. It accepts `localhost`, IP literals, the
+bind host, `.ts.net`, `.trycloudflare.com`, `.cfargotunnel.com`, and the active managed
+tunnel.
+
+**Your own domain is not on that list.** Add it:
+
+```bash
+CODEMAN_ALLOWED_HOSTS='codeman.example.com,.internal.example.com'
+```
+
+A bare entry matches that exact host; a leading dot matches subdomains. Without this, a
+correctly configured proxy still gets `403 host not allowed`, which reads like a proxy bug
+and is not one.
+
+Also make sure the proxy forwards WebSocket upgrades. The terminal is a WebSocket, and the
+upgrade runs the same Host and Origin checks, closing with code `4003` on failure.
+
+### Mounting under a sub-path
+
+By default Codeman assumes it is served at the origin root (`/`). To mount it under a
+sub-path — e.g. `https://example.com/codeman/` — start it with `--base-url` (or the
+`CODEMAN_BASE_URL` env var):
+
+```bash
+codeman web --base-url /codeman
+# or
+CODEMAN_BASE_URL=/codeman codeman web
+```
+
+The value is a plain path prefix; `/` (the default) means "mounted at the root". With a
+prefix set, Codeman emits every URL — the HTML shell and its assets, API/SSE/WebSocket
+calls, redirects, the PWA manifest and the service worker — under that prefix, so a browser
+loading `https://example.com/codeman/` stays inside the mount.
+
+**Forward the prefix unchanged — do NOT strip it.** Codeman expects the proxy to pass the
+full path (including `/codeman/`) straight through. A minimal nginx block:
+
+```nginx
+location /codeman/ {
+    proxy_pass         http://127.0.0.1:3000;   # note: no trailing slash — keep the /codeman/ prefix
+    proxy_http_version 1.1;
+    proxy_set_header   Host              $host;
+    proxy_set_header   Upgrade           $http_upgrade;   # WebSocket
+    proxy_set_header   Connection        "upgrade";
+}
+```
+
+Notes and current limits:
+
+- The prefix must still be paired with `CODEMAN_ALLOWED_HOSTS` for your domain, exactly as
+  above — the two are independent.
+- Health checks, Claude Code hooks and the docker bridge connect to the raw port directly
+  (bypassing the proxy), so Codeman also keeps answering at the un-prefixed paths on the port
+  itself. Nothing about those flows changes.
+- **Web-tab (dashboard) proxying** is base-path aware: proxied dashboards have their injected
+  `<base>` tag, root-absolute asset rewrites, runtime `fetch`/XHR shim, `Set-Cookie` paths, and
+  redirects all rebased onto the mount, so they load the same under `--base-url` as at the root.
+
+## Session cookies and rate limits
+
+The first request prompts for HTTP Basic credentials. On success the server issues an opaque
+`codeman_session` cookie (24 hour lifetime, extended on activity, validated server-side so
+it cannot be forged offline). Ten failed attempts from one IP produce a `429` with a 15
+minute decay.
+
+A valid cookie or a correct password recovers immediately even while an attacker is hammering
+the same IP, which matters because all tunnel traffic arrives from one loopback address.
+
+## Terminal alternatives
+
+You do not have to use a browser. `codeman tui` is a full-screen session dashboard that
+works well in SSH clients like Termius or Blink:
+
+```bash
+codeman tui           # the dashboard
+codeman tui 2         # attach straight to session 2
+codeman tui --list    # numbered list, then exit
+```
+
+`Enter` attaches into the pane and `F1` comes back. Under 72 columns it drops the preview
+and becomes a single-column list, so it stays usable on a phone. The sessions are the same
+ones the dashboard shows. See [docs/tui.md](https://github.com/Ark0N/Codeman/blob/master/docs/tui.md)
+for the full guide.
+
+## Common problems
+
+| Symptom                                                     | Cause and fix                                                                                          |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `403 host not allowed`                                       | Your domain is not in the allowlist. Set `CODEMAN_ALLOWED_HOSTS`.                                       |
+| Assets 404 / blank page under a sub-path                     | Start Codeman with `--base-url /<prefix>` and have the proxy forward the prefix unchanged (don't strip it). |
+| Phone shows the login page but the terminal never connects   | The proxy is not forwarding WebSocket upgrades.                                                         |
+| Browser warns about the certificate                          | Expected with `--https` and its self-signed certificate. Tailscale gives you a real one instead.        |
+| LAN IP does not respond, but a tunnel to the same box works  | The server is bound to loopback. That is the default. A tunnel reaches it; a LAN browser cannot.        |
+| Hooks stopped working after switching to HTTPS               | Hook callbacks need `-k` for the self-signed certificate. Recent versions self-heal existing cases; if yours predates that, recreate the case's hooks. |
+| Everything is slow over the tunnel                           | Quick tunnels route through Cloudflare's edge. Tailscale is usually a direct connection and much faster. |
+
+## Read next
+
+- [Security](Security) - the whole model, and the hardening checklist.
+- [Mobile Guide](Mobile-Guide) - once you can reach it from the phone.
+- [Running As A Service](Running-As-A-Service) - keeping server and tunnel up across reboots.
+- [`docs/security-architecture.md`](https://github.com/Ark0N/Codeman/blob/master/docs/security-architecture.md) - the full model.

docs/wiki/Remote-SSH-Sessions.md

@@ -0,0 +1,112 @@
+# Remote SSH Sessions
+
+Point a case at another machine and the agent runs **there**, with the same dashboard,
+mobile UI, and autonomy features. Your laptop becomes a window onto a session living on the
+remote host.
+
+Like Docker, this is a **location overlay** on a case, not a run mode. All ten run modes
+work remotely. See [Core Concepts](Core-Concepts).
+
+## Why bother
+
+The agent runs where the work is: a build server, a NAS, a GPU box, a machine reachable only
+through a jump host. Your laptop can sleep, change networks, or close, and the run continues.
+
+## Setting it up
+
+**Add Case → Remote**:
+
+| Field                 | Notes                                                                |
+| --------------------- | -------------------------------------------------------------------- |
+| **Host**              | Hostname or IP.                                                       |
+| **Username**          | The SSH user.                                                         |
+| **Port**              | Defaults to 22.                                                       |
+| **Identity file**     | `~` and `$HOME` are expanded for you.                                 |
+| **Jump host**         | The `-J` equivalent, `[user@]host[:port]`.                            |
+| **SOCKS proxy**       | For hosts reachable only through a proxy.                             |
+| **Extra SSH options** | Any `KEY=VALUE` options your normal connection needs.                 |
+| **Remote path**       | The working directory on that machine.                                |
+
+Hosts are saved and reusable, so a second case on the same machine is just a path. Host
+profiles can also carry per-run-mode launch command overrides, for when the binary lives
+somewhere unusual on that host.
+
+The remote host needs **tmux**. Codeman probes for it when you link the host rather than
+failing later at launch.
+
+## What actually runs
+
+The agent lives inside a dedicated tmux server on the **remote** host, and Codeman fronts it
+with a local tmux pane running `ssh`.
+
+That two-layer arrangement is what makes it durable: a dropped SSH connection, a network
+change, or a closed laptop kills the local pane, not the remote session. Reconnecting lands
+back in the same live conversation.
+
+The remote session name is deliberately chosen so that a Codeman **running on the target
+host** will not adopt it as one of its own. Two Codemans, one host, no interference.
+
+## Auto-reconnect
+
+A watcher with bounded backoff notices a dead SSH pane and quietly reattaches to the still
+running remote session. On by default; the kill switch is in
+**App Settings → Agents & CLIs → Remote auto-reconnect**.
+
+Intentional kills are never revived. Closing a session means closing it. Neither is a clean
+exit inside the pane (Ctrl-D, `exit`, Ctrl-C at the CLI's prompt): that tears the remote
+tmux session down, and the watcher revives a session only when that durable session is
+verifiably still alive. Only a transport drop is reconnected.
+
+## Discover and attach
+
+Codeman can list the `codeman-*` sessions already running on a host, whether that machine's
+own Codeman started them or another operator did, and attach to one.
+
+The distinction that matters:
+
+| Session      | On tab close                                    |
+| ------------ | ------------------------------------------------ |
+| **Launched** | Killed, like any local session.                  |
+| **Attached** | **Detached, never killed.**                      |
+
+Attaching to someone else's session and closing your tab must not end their run, so it does
+not. Several clients can attach the same remote session at different window sizes without
+clamping each other, and discovery shows a shared badge with the client count.
+
+## Files
+
+Previews, downloads and text reads in a remote case go over the same ssh connection the
+session uses, so a clicked path opens the file on the machine the agent is on, `Range`
+seeking included. Nothing is copied to the Codeman host. Editing, Office previews,
+thumbnails, the file tree and the tail viewer are not available remotely and answer a clear
+400 rather than a misleading 404. Details in [Working With Files](Working-With-Files).
+
+## Security
+
+Every SSH command line in Codeman flows through one builder that shell-escapes every
+user-supplied field: identity paths, jump hosts, proxy commands, and extra options. That is
+the entire injection surface, and it is deliberately a single function rather than string
+concatenation spread across the codebase.
+
+Host, path, and identity fields are schema-validated on top of that.
+
+Codeman does not store SSH passwords. Use keys, as you would for any other automation.
+
+## Gotchas
+
+- **The remote host needs tmux.** Probed at link time, so you find out immediately.
+- **The local working directory is meaningless** for a remote session, and is not used.
+- **Run flows must go through the quick-start path** for remote cases. This matters if you
+  are driving Codeman over the API: the plain session-create endpoint validates the working
+  directory locally and has no case concept, so it will reject or misroute a remote case.
+- **Latency is SSH latency.** Local echo helps the typing feel, but a slow link is a slow
+  link.
+- **Transcript-backed features follow the transcript.** Subagent windows and similar surfaces
+  read files on the machine where the agent runs.
+
+## Read next
+
+- [Core Concepts](Core-Concepts) - overlays versus run modes.
+- [Docker Cases](Docker-Cases) - the other overlay.
+- [Security](Security) - the wider model.
+- [`docs/remote-sessions.md`](https://github.com/Ark0N/Codeman/blob/master/docs/remote-sessions.md) - the full design.

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

@@ -0,0 +1,218 @@
+# Running As A Service
+
+Keeping Codeman up: past the shell you started it in, past a logout, past a reboot. Plus
+logs, updates, and running more than one instance.
+
+## Three levels
+
+| Level                | Survives                                  | Command                   |
+| -------------------- | ----------------------------------------- | ------------------------- |
+| Foreground           | Nothing. Dies with the terminal.           | `codeman web`             |
+| Detached             | Closing the shell and logging out.         | `codeman web -d`          |
+| Service              | Reboots.                                   | `codeman service install` |
+
+Agents themselves survive all three, because they live in tmux. Stopping the server never
+stops the agents.
+
+## Detached mode
+
+```bash
+codeman web -d          # start detached; logs to ~/.codeman/web.log
+codeman web --status    # is it up, and on which pid
+codeman web --stop      # graceful stop; agents keep running
+```
+
+`-d` waits until the server actually answers before reporting success, so a port clash never
+reads as a successful start.
+
+Two implementation details that explain the behaviour:
+
+- It relaunches the same entry script detached, so there is no controlling terminal and no
+  shell job entry. `nohup` is **not** what makes this work: Node re-arms the hangup signal to
+  its default even when it inherits "ignore", and Codeman handles that signal with a graceful
+  shutdown, so a delivered hangup would still stop the server.
+- `--stop` verifies the process still looks like a Codeman server before signalling it,
+  because process ids get recycled.
+
+**It refuses to start a second server on the same data directory.** Two servers sharing a
+tmux socket attach to each other's live sessions.
+
+## Installing as a service
+
+```bash
+codeman service install     # systemd user unit on Linux, LaunchAgent on macOS
+codeman service status
+codeman service uninstall
+```
+
+The installer's final menu offers this too.
+
+Notable behaviours:
+
+- **Your PATH is baked into the unit.** launchd hands a job
+  `/usr/bin:/bin:/usr/sbin:/sbin`, which finds neither a Homebrew or nvm `node` nor `tmux`
+  or `claude`. This is the single most common cause of a hand-written unit that starts and
+  immediately dies.
+- **`CODEMAN_PASSWORD` is never written into the unit file.** Add it yourself if the service
+  needs authentication.
+- **It refuses when a server is already running** on that data directory, for the same reason
+  detached mode does.
+- **It verifies rather than assumes.** `launchctl load` and a clean spawn are both silent
+  about a server that starts and immediately exits, so the parent polls until the child
+  answers or dies.
+
+On Linux, if you want the service running while you are not logged in:
+
+```bash
+loginctl enable-linger $USER
+```
+
+On macOS, a LaunchAgent starts when you log in, not at boot. A headless Mac (no GUI login)
+needs a system LaunchDaemon instead, written by hand as root. The installer recognises an
+existing `/Library/LaunchDaemons/com.codeman.web.plist` and leaves it alone rather than
+installing a LaunchAgent next to it, since the two would fight over the port; remove the
+daemon first if you want to switch. The same login caveat applies to the App Store and
+standalone Tailscale apps, so on a headless Mac the Tailscale URL only comes back after a
+reboot if the open-source `tailscaled` is used.
+
+### Writing the unit by hand
+
+**Linux (systemd user unit):**
+
+```bash
+mkdir -p ~/.config/systemd/user
+cat > ~/.config/systemd/user/codeman-web.service << EOF
+[Unit]
+Description=Codeman Web Server
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=$(which node) $HOME/.codeman/app/dist/index.js web
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+EOF
+systemctl --user daemon-reload
+systemctl --user enable --now codeman-web
+loginctl enable-linger $USER
+```
+
+**macOS (LaunchAgent):**
+
+```bash
+mkdir -p ~/Library/LaunchAgents
+cat > ~/Library/LaunchAgents/com.codeman.web.plist << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.codeman.web</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>$(which node)</string>
+    <string>$HOME/.codeman/app/dist/index.js</string>
+    <string>web</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key>
+  <string>/tmp/codeman.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/codeman.log</string>
+</dict>
+</plist>
+EOF
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist
+```
+
+Prefer `codeman service install` where you can. It handles the PATH problem for you.
+
+## Logs
+
+```bash
+journalctl --user -u codeman-web -f    # systemd
+tail -f ~/.codeman/web.log             # detached mode
+log stream --predicate 'process == "node"'   # macOS, noisy
+```
+
+## Updating
+
+| Install route | Update with                                                             |
+| ------------- | ------------------------------------------------------------------------ |
+| Installer     | Re-run the one-liner, or **App Settings → System → Updates**.             |
+| npm           | `npm update -g aicodeman`                                                 |
+| git clone     | `git pull && npm install && npm run build`, then restart.                 |
+| Docker Compose | Re-run `Start-Codeman.sh`, or the in-app updater, which restarts the container in place. |
+
+### The in-app updater
+
+**App Settings → System → Updates**, for git-clone installs supervised by systemd or
+launchd. npm installs report as non-updatable, and an unsupervised install is told to
+restart manually.
+
+The interesting part is that the update restarts the very process running it. So the real
+work runs in a **detached script that outlives the restart** and writes progress to a status
+file, which the browser polls across the connection drop. A dirty tree is stashed rather
+than discarded.
+
+### After updating
+
+Sessions are unaffected: they live in tmux and the server reattaches. If the UI looks stale,
+reload; on iOS Safari, close the tab completely and reopen.
+
+## Running two instances
+
+The data directory and the tmux socket are process wide, so a second server on the defaults
+will discover and attach the first one's sessions. Scope both together:
+
+```bash
+CODEMAN_INSTANCE=beta CODEMAN_PORT=5000 codeman web
+```
+
+Service unit names are instance-scoped too, so a beta instance can be installed as its own
+service without colliding with the main one. `CODEMAN_DATA_DIR` and `CODEMAN_TMUX_SOCKET`
+exist for the rare case where they need to differ, but setting only one of them recreates
+exactly the problem you were avoiding.
+
+## Running Codeman itself in Docker
+
+The Compose deployment in `docker/` runs the server in a container and spawns Docker cases
+as sibling containers through the mounted host socket. Start it with
+`bash docker/Start-Codeman.sh` rather than a bare `docker compose up`: the script pre-creates
+the bind-mounted directories with the right owner, honours a `docker-compose.override.yml`,
+and refreshes the build volumes when the checkout moved under them. The in-app updater
+applies code only and restarts by letting the container exit, so it refuses a release that
+changes the Dockerfile, the compose file, or adds a new `.env` key, until you re-run the
+script. Guide:
+[`docker/README.md`](https://github.com/Ark0N/Codeman/blob/master/docker/README.md).
+
+## The tunnel as a service
+
+```bash
+systemctl --user enable codeman-tunnel
+loginctl enable-linger $USER
+```
+
+Or the toggle in **App Settings → System → Remote access**. See
+[Remote Access](Remote-Access).
+
+## Health checks
+
+```bash
+curl -s localhost:3000/api/status | jq '.version, .uptime'
+codeman web --status
+codeman doctor
+```
+
+Add `-k` and the `https://` URL on an HTTPS install.
+
+## Read next
+
+- [Installation](Installation) - the routes and what each supports.
+- [Remote Access](Remote-Access) - exposing it once it stays up.
+- [Troubleshooting](Troubleshooting) - when it does not.

docs/wiki/Security.md

@@ -0,0 +1,121 @@
+# Security
+
+The honest version first: **Codeman's dashboard is a remote code execution surface, by
+design.** It starts agents with permission prompts skipped by default, so anyone who can
+reach it can run arbitrary code as your user, on your machine. Every protection in Codeman
+exists to control who that is.
+
+That is not a flaw to be fixed. It is what "run my coding agent for me" means. The job is to
+make sure the set of people who can reach it is exactly the set you intended.
+
+## The default is safe
+
+A bare `codeman web` binds `127.0.0.1`. Only processes on that machine can reach it, which
+is why shipping with no password by default is defensible. Everything risky starts when you
+expose it.
+
+## Hardening checklist
+
+In order of how much they matter:
+
+1. **Do not expose it without `CODEMAN_PASSWORD`.** Binding a non-loopback host without one
+   starts, but warns loudly. A tunnel refuses outright unless you acknowledge the exposure
+   in the UI.
+2. **Prefer Tailscale over a public tunnel.** Keeping the loopback bind and putting a
+   private network in front of it removes the public attack surface entirely, and gives you
+   real HTTPS. See [Remote Access](Remote-Access).
+3. **Use a long password.** It is the only thing between a public URL and your shell.
+4. **Consider the permission mode.** **App Settings → Agents & CLIs → Claude → Startup
+   Mode** can switch new sessions from skip-prompts to Anthropic's classifier-guarded `auto`
+   mode, to normal prompting, or to an explicit allowed-tools list.
+5. **Use Docker cases for untrusted work.** If you are pointing an autonomous loop at a repo
+   you did not write, [Docker Cases](Docker-Cases) gives it its own filesystem and network
+   for the cost of one checkbox.
+6. **Keep it updated.** Browser-driven attack paths were closed in 0.9.x and hardening is
+   ongoing.
+
+## What protects what
+
+These run on **every** request, including on a default no-password loopback install:
+
+| Layer                        | What it stops                                                                                  |
+| ---------------------------- | ----------------------------------------------------------------------------------------------- |
+| **Host-header allowlist**    | DNS rebinding. A domain rebound to `127.0.0.1` is rejected before any handler runs. Add your own domains with `CODEMAN_ALLOWED_HOSTS`. |
+| **Cross-site Origin guard**  | CSRF on state-changing requests. A *missing* Origin is allowed so curl, the CLI, and hooks keep working; a foreign or opaque one is rejected. |
+| **Raw `text/plain` bodies**  | The CORS simple-request CSRF vector, where a cross-site form could smuggle JSON into a write route with no preflight. |
+| **WebSocket origin check**   | Cross-site WebSocket hijacking. The terminal upgrade closes with code `4003` on failure.        |
+| **Output escaping**          | Stored XSS from agent-derived strings: tool names, command arguments, subagent descriptions.     |
+| **Security headers**         | A strict content security policy, `nosniff`, frame options, and HSTS over HTTPS. CORS is reflected only for loopback origins. |
+
+When authentication is enabled:
+
+| Layer               | Behaviour                                                                                       |
+| ------------------- | ------------------------------------------------------------------------------------------------ |
+| **HTTP Basic**      | `CODEMAN_USERNAME` (default `admin`) and `CODEMAN_PASSWORD`.                                      |
+| **Session cookie**  | A 256-bit opaque token validated server side, so it cannot be forged offline. 24 hours, extended on activity, with a device-context audit trail. |
+| **Rate limiting**   | Ten failed attempts per IP produce a `429` with a 15 minute decay. A correct password or valid cookie recovers immediately even under attack, which matters because all tunnel traffic shares one loopback address. |
+| **QR auth**         | Single-use 60-second tokens with their own separate rate limiter, so a mistyped password cannot lock out QR login. |
+| **Hook endpoints**  | The hook and telemetry endpoints skip Basic auth because they are called from localhost by the CLI, but when auth is on, that bypass additionally requires a per-instance hook secret. |
+
+## File access
+
+Three separate file surfaces, each confined differently, because a single shared rule would
+be wrong for at least one of them:
+
+| Surface              | Rules                                                                                      |
+| -------------------- | -------------------------------------------------------------------------------------------- |
+| **File Viewer**      | Real path resolution before boundary checks, so symlinks cannot escape. Sensitive trees blocked. Edit mode adds an extension allowlist, a size cap, `.git` denial, and optimistic concurrency. It never creates files. |
+| **Attachments**      | An id-based registry, so browser requests never carry absolute paths. The magic-link scanner is prompt-injectable by nature and is therefore force-confined to the session's workspace. Extension allowlist, not a blocklist. |
+| **Path picker**      | Its own root allowlist rather than the workspace confinement. In multi-user mode a non-admin gets only their own user space, because per-user spaces live inside the home directory. |
+| **Remote cases**     | Reads go over the session's own ssh connection and are resolved and contained on the remote host, with a bounded number of ssh children. Nothing is copied to the Codeman host; writes, Office previews and thumbnails are refused. |
+
+Downloads block sensitive paths outright (`.env`, credentials files, `~/.ssh`, AWS
+credentials), and SVG and HTML are served as downloads with `nosniff` so they cannot execute
+in the page.
+
+## Supply chain and isolation
+
+- Security-sensitive transitive dependencies are pinned to patched versions, and lockfile
+  integrity is checked on every push and pull request: every entry must resolve to the public
+  registry with a hash.
+- Public assets are scanned for NUL bytes and syntax-checked in CI.
+- `CODEMAN_INSTANCE` scopes the tmux socket and the data directory together, so two
+  instances never attach each other's live sessions.
+
+## What Codeman does not protect against
+
+Stated plainly, because a security page that only lists strengths is not useful:
+
+- **Multi-user mode is not a sandbox.** It separates workspaces. Every session still runs as
+  the same OS account, so a determined user's agent can reach another user's files. For real
+  isolation, pair users with Docker cases or run separate instances under separate OS
+  accounts.
+- **An agent you gave shell access can do anything you can.** Permission modes narrow this;
+  they do not remove it.
+- **A tunnel makes your machine reachable from the internet.** The password is the whole
+  boundary. Treat it accordingly.
+- **Codeman cannot detect your own loopback reverse proxy**, which is why the hook-endpoint
+  bypass requires a secret unconditionally when auth is on.
+- **The agent CLIs have their own trust models.** Pi's project trust executes repo-local
+  TypeScript, for instance. See [Agent CLIs](Agent-CLIs).
+
+## Privacy
+
+No telemetry, no analytics, no phone-home. Codeman's only network traffic is between your
+browser and your server. Your agent CLI's traffic is its own, on your account.
+
+Two features send data outward, both off by default and both stated where they appear: voice
+dictation through your Claude login, and the Read My Mind prediction call.
+
+## Reporting a vulnerability
+
+**Never in a public issue.**
+[SECURITY.md](https://github.com/Ark0N/Codeman/blob/master/.github/SECURITY.md) has the
+private disclosure process and the current list of known limitations.
+
+## Read next
+
+- [Remote Access](Remote-Access) - the safe ways to expose it.
+- [Multi-User Mode](Multi-User-Mode) - what it does and does not separate.
+- [Docker Cases](Docker-Cases) - real isolation for untrusted work.
+- [`docs/security-architecture.md`](https://github.com/Ark0N/Codeman/blob/master/docs/security-architecture.md) - the complete model.