fix(tui): kill a cancelled boot's pane when it settles + make async tests actually count

Folds in the independent review's remaining nit — and, in proving the nit's fix, uncovers two defects in the test suite itself. ## The nit (latent M1b, second costume) `_cancelBooting` kills BY NAME, but the tmux session only EXISTS once `bootPane` has run — and `bootPane` is queued on a microtask. So a caller doing `refill()` then `drain()` in the SAME synchronous block leaves `_cancelBooting` with nothing to kill (a no-op); it bumps the generation, and the boot microtask then CREATES the session, succeeds, and — under the old bare `return` on a stale generation — walked away from a LIVE authenticated `claude` that nothing owns. Reproduced: reverted: drain() kills nothing (no session yet) -> boot creates it -> ORPHAN: ['p1'] fixed : drain() kills nothing (no session yet) -> boot creates it -> boot kills it -> [] Not reachable from any current call site, so this is defense-in-depth — but ADR 0008 and the reap-tick comment in server.mjs BOTH explicitly contemplate a boot-time pre-warm, which is exactly the shape that reaches it. Killing an already-dead session is a harmless no-op, so the fix is idempotent whichever way the race lands. ## Defect 1 in the suite: async tests were never awaited (44 of them) Writing the regression guard exposed this. `test()` called `fn()`, got a promise back, and IMMEDIATELY printed ✓ and incremented `passed` — without awaiting it. For all 44 tests written as `test("...", async () => {...})`: - ✓ meant "did not throw SYNCHRONOUSLY", not "passed"; - a failed assertion escaped as an unhandled rejection, crashing the process (CI stays red on the non-zero exit) but never being COUNTED — so the summary could print "0 failed" and be wrong. The suite's headline number was therefore not evidence for ANY async test, including this PR's own M1a/M1b guards. `test()` now settles an async body before counting it, and the summary awaits them. ## Defect 2, exposed the instant defect 1 was fixed: a false guard `"a boot that resolves AFTER a drain kills its own pane ... no orphan process left behind"` asserted `killed.length === 1` — i.e. that kill was CALLED once. But `_cancelBooting`'s kill-by-name on a not-yet-existent session is a NO-OP that still increments that counter. So "kill was called once" and "a live session is orphaned" were both true at the same time: a test named for the absence of an orphan was passing while the orphan was present. Now asserts LIVENESS (`live.size === 0`) — the only honest question. ## Evidence fix present : 295 passed, 0 failed, exit 0 fix reverted: 293 passed, 2 failed <- BOTH liveness guards fire (the old kill-count guard did not) Also: `dropped`'s doc comment now lists `cancelled` (a cancelled in-flight boot lands there via _drop). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VqgWJcjxrjjL9L9SkpZyXR
feat(tui): warm pane pool — single-use pre-booted panes, opt-in via OCP_TUI_POOL_SIZE
2026-07-21 21:15:09 +00:00 · 2026-07-13 16:50:35 +10:00 · 2026-07-13 16:38:03 +10:00 · 2026-07-13 16:30:55 +10:00 · 2026-07-13 15:16:30 +10:00 · 2026-07-13 14:22:17 +10:00
20 changed files with 3209 additions and 200 deletions
@@ -1,5 +1,15 @@
 # Changelog

+## v3.21.1 — 2026-07-07
+
+Patch release: three bug fixes from an independent concurrency/session-lifecycle audit, each its own PR with a fresh-context reviewer (Iron Rule 10). No new `cli.js` wire behavior, no new endpoint, header, or env var; the `/health` field set is unchanged (only value truthfulness improved).
+
+### Fixed
+
+- **TUI session-scope / boot-reap (#148)** — `lib/tui/session.mjs`'s tmux session prefix is now scoped per-instance by listen port (`ocp-tui-<port>-`) instead of a bare host-wide `ocp-tui-` constant, so a second OCP instance on the same host (e.g. a temporary verification instance) can no longer have its live TUI sessions reaped or `kill-server`'d by another instance's boot/periodic sweep. The one-time boot reap also claims exact-shape legacy `ocp-tui-<8hex>` sessions (pre-fix naming) once, to clean up zombies left behind across an in-place upgrade.
+- **`-p` spawn-token mutex + keychain caching (#150)** — the real-HOME token fallback used when the keychain token is within its 5-minute expiry window is now serialized behind a mutex, so concurrent `-p` spawns no longer race the same single-use refresh token against each other (the credential-fork hazard). Added a 30s TTL cache + last-good-label memoization for the keychain read, cutting per-spawn event-loop blocking. The isolation decision (`/health` isolated/real-home reporting) is now re-evaluated per spawn instead of memoized forever, so `/health` no longer misreports a stale decision. New module `lib/spawn-auth.mjs` extracts the pure, unit-testable primitives (mutex, TTL cache, expiry gate, label ordering).
+- **Concurrency queue / disconnect handling (#149)** — the shared semaphore now honors a runtime-lowered `maxConcurrent` immediately (previously a decrease was silently ignored until in-flight tasks finished on their own) and wakes queued waiters right away when the limit is raised. Queued `-p`/TUI requests are now linked to the client's HTTP connection via `AbortSignal`; a client that disconnects while queued is spliced out of the queue instead of still spawning `claude` once a slot frees. A singleflight follower whose leader disconnected now retries instead of inheriting a spurious 500, and a queued-then-disconnected request is no longer recorded as a usage failure or logged as an error (quiet disconnect handling).
+
 ## v3.21.0 — 2026-06-25

 Cleanup + docs release: TUI dead-code removal, docs honesty, and release prep. No new `cli.js` wire behavior; the default path (`CLAUDE_TUI_MODE` unset) is byte-for-byte unchanged.
@@ -894,6 +894,10 @@ node ~/ocp/scripts/sync-openclaw.mjs

 This is read-only at startup; the warning never blocks the gateway from running.

+### A TUI session vanished right after upgrading OCP
+
+If you ran a pre-3.21.1 OCP instance and a post-3.21.1 instance on the same host at the same time during an upgrade, the new instance's one-time boot reap can, once, kill an old-format (`ocp-tui-<8hex>`) live TUI session belonging to the still-running old instance — restart the affected session (`ocp restart` or re-run your TUI turn) and it will come back under the new instance's port-scoped naming.
+
 ### OpenClaw shows old models after `ocp update` (v3.10→v3.11 only)

 One-time bootstrap quirk for the v3.10.0 → v3.11.0 jump only — the running shell had the old `cmd_update` cached. Run once manually:
@@ -954,7 +958,9 @@ See [Subscription-pool (TUI) mode](#subscription-pool-tui-mode) and ADR 0007 PR-
 | `OCP_TUI_CWD` | `$HOME/.ocp-tui/work` | (TUI-mode) Scratch working directory where interactive claude sessions run. Transcripts land under `<HOME>/.claude/projects/<encoded-cwd>/`. Created automatically. |
 | `OCP_TUI_HOME` | *(auto)* | (TUI-mode) `HOME` claude runs under. **When unset, OCP picks it for you:** if `CLAUDE_CODE_OAUTH_TOKEN` is set → a **credential-isolated** scratch home `$HOME/.ocp-tui/home` (no `credentials.json`, env-token auth — **recommended**); if no env token → the operator's real home (legacy shared `credentials.json`). Setting this to an **explicit** path overrides the auto-default. The credential handling at that path still follows the env token: **with** the env token it is credential-free (env-token auth, no `credentials.json` written); **without** the env token (and the path ≠ real home) it uses the legacy symlinked-credentials scratch mode, which carries the credential-fork caveat — see ADR 0007. |
 | `OCP_TUI_ENTRYPOINT` | `cli` | (TUI-mode) Billing-classifier labeling: `cli` (default) pins `cc_entrypoint=cli` deterministically; `auto` lets claude self-classify via TTY detection; `off` leaves the inherited env untouched. Honest only when the spawn is a genuine interactive PTY — see ADR 0007. |
+| `OCP_TUI_EFFORT` | `low` | (TUI-mode) Effort level passed to the interactive `claude` as an explicit `--effort` flag: `low` (default), `medium`, `high`, `xhigh`, `max`, or `inherit` to omit the flag (the pre-flag behaviour: the pane inherits a HOME-dependent effort — the operator's `~/.claude/settings.json` `effortLevel` in real-home mode, claude's built-in default in env-token scratch mode). Explicit `low` cuts measured TTFT p50 by ~40% and collapses run-to-run variance ~15× versus an inherited `xhigh` (see `docs/plans/2026-07-13-tui-latency/`); proxied requests rarely benefit from extended thinking. Banner-verified to stay on the subscription pool (`· Claude Max`). An invalid value logs a warning and falls back to `low`. |
 | `OCP_TUI_MAX_CONCURRENT` | `2` | (TUI-mode) Max concurrent interactive TUI turns. **Independent** of `CLAUDE_MAX_CONCURRENT` (which bounds the `-p`/stream-json path; TUI never uses it). A TUI turn is heavy (per-request cold-boot of tmux+claude + up to `CLAUDE_TUI_WALLCLOCK_MS` wallclock), so the default is low to keep small hosts (e.g. a Pi 4) alive under a burst. Excess turns **queue** (bounded); a full queue yields a 503. See ADR 0007 PR-B amendment. |
+| `OCP_TUI_POOL_SIZE` | `0` (off) | (TUI-mode) Number of **pre-booted warm `claude` panes** kept ready, so a request does not pay the cold boot. `0` disables the pool entirely — the request path is then exactly the cold-boot path. Max `4`; an unparseable value disables it rather than guessing. **Measured on a Mac mini (Sonnet 4.6, `--effort low`): end-to-end p50 `10.17s` (n=6, pool off) → `6.00s` (n=12 warm hits) — −4.2 s / −41%** — the pool recovers both the ~1.2 s boot *and* ~2.9 s of post-input-bar init that a pane which has been idle a moment has already finished. **Cost:** each warm pane is a *live idle `claude` process* held whether or not a request ever arrives (peak processes ≈ pool size + `OCP_TUI_MAX_CONCURRENT` + 1 booting replacement) — which is why it is opt-in. Panes are **single-use**: one turn, then killed and replaced in the background. The **first request after start (and after any model switch) is always a cold miss** — the pool warms the most recently requested model, since OCP cannot know which model the next caller wants. See `docs/plans/2026-07-13-tui-latency/`. |
 | `OCP_SKIP_AUTH_TEST` | *(unset)* | When `=1`, skip the `claude -p` auth probe during `setup.mjs`. After 2026-06-15 this probe draws from the Agent SDK credit pool; set this to avoid burning a metered credit on re-installs or `ocp update` runs. Auth is validated at the first real request. |
 | `OCP_TUI_FULL_TOOLS` | *(unset)* | (TUI-mode, **single-user only**) When `=1`, grant the interactive session the **same tool surface as the `-p` path** — `--allowedTools` (+ optional `--mcp-config`, read from `CLAUDE_ALLOWED_TOOLS` / `CLAUDE_MCP_CONFIG`) — instead of the default MCP-walled, built-in-tools-only set. Lets a trusted single-operator TUI deployment run a **tool-using / MCP agent** (e.g. an OpenClaw assistant) on the subscription pool. Safe because TUI **refuses to boot under `AUTH_MODE=multi`** (hard exit) — no guest key can ever reach the TUI path, so this gate cannot expose tools to an untrusted caller. (Under `AUTH_MODE=shared` + `OCP_TUI_ALLOW_LAN=1`, anyone holding the single shared key reaches it — that is the existing TUI trust model, unchanged.) Note: `--dangerously-skip-permissions` / `CLAUDE_SKIP_PERMISSIONS` is **not** supported for TUI — claude v2.1.x shows an interactive bypass-acceptance screen in headless tmux that cannot be answered, bricking the pane. Use scratch-home `settings.json` `additionalDirectories` instead. See [Subscription-pool (TUI) mode](#subscription-pool-tui-mode) and ADR 0007. |

@@ -1028,13 +1034,43 @@ Then restart OCP. At boot you will see (with the env token set, isolated home au
 ### What changes / what doesn't

 - **Callers see no API change.** The response is a normal OpenAI completion object or chunked SSE — identical wire format.
- **No real token streaming.** TUI-mode buffers the full response then replays it as chunked SSE. You will see a delay then the complete response rather than real-time tokens.
+- **No real token streaming *today* — but it is achievable, and planned.** TUI-mode currently buffers the full response then replays it as chunked SSE: you see a delay, then the complete response. This is a limitation of the current implementation, **not** of the path — `claude` fires a `MessageDisplay` hook carrying incremental, byte-faithful `delta`s of the raw reply (they concatenate exactly to the final text, and stay prefix-stable), on the subscription pool, without `-p`. Wiring it into OCP's SSE is tracked as backlog item #2. What is *not* available is token-by-token granularity (the hook fires once per rendered block — roughly one per paragraph, list item, or code block, so the count scales with answer length) — which is plenty for SSE. Evidence: [`docs/plans/2026-07-13-tui-latency/streaming-spike.md`](docs/plans/2026-07-13-tui-latency/streaming-spike.md).
 - **Cache and singleflight work normally.** TUI-mode writes the buffered response to the cache on success; cache-hits skip the interactive turn entirely.
 - **The host's `CLAUDE.md` / auto-memory is never injected.** OCP is a proxy — the proxied client (OpenClaw / your IDE) owns its own context and memory. TUI-mode always runs `claude` with `CLAUDE_CODE_DISABLE_CLAUDE_MDS` + `CLAUDE_CODE_DISABLE_AUTO_MEMORY`, so a `CLAUDE.md` on the OCP host can never leak into proxied turns (verified live; see #4). Built-in tool schemas + the interactive system prompt remain (the inherent ~20–35K context floor of interactive mode); MCP is hard-disabled.
 - **Authenticate via `CLAUDE_CODE_OAUTH_TOKEN` in a credential-isolated home (recommended).** tmux does not forward the parent process's env to the pane, so OCP sets the token explicitly on the spawned `claude` when `CLAUDE_CODE_OAUTH_TOKEN` is present. But passing the token is **not enough on its own**: interactive `claude` *prefers* `~/.claude/.credentials.json` over the env var (unlike the `-p` path), so a stale `credentials.json` would shadow the token. With the env token set and `OCP_TUI_HOME` unset, OCP therefore runs claude in a **credential-isolated home** (`$HOME/.ocp-tui/home`) that has **no `credentials.json`** — so the env token is the only credential and is authoritative, and claude never runs the token-refresh path (so the single-use refresh token can't be corrupted by the spawn/teardown cycle). On a long-running host the credentials.json path produced a permanent `Please run /login · API Error: 401` that re-login could not fix (the next spawn re-corrupted it); the isolated home ends that at the root. Transcripts land under the same isolated home, so the answer-reader is unaffected. Without the env token, claude falls back to the real home's `credentials.json` (byte-for-byte the previous behaviour). (The token is visible in `ps` on the pane command — acceptable for the single-user A-path; the multi-user B-path is refused at boot.) See ADR 0007 PR-C / PR-D amendments.
 - **Stale tmux sessions are reaped.** The pane's `claude` is a child of the tmux server (not OCP), so OCP cannot reap it directly; `claude` zombies can otherwise accumulate as `<defunct>` over a long-running host. OCP reaps them at boot and on a 15-min idle sweep by issuing `tmux kill-server` — but **only when no foreign tmux session remains** (it never disrupts a co-hosted `olp-tui-*` instance). See ADR 0007 PR-C amendment.
 - **Default path unchanged.** Unset `CLAUDE_TUI_MODE` and restart → `callClaude` / `callClaudeStreaming` are used again, byte-for-byte identical to today.
 - **Concurrency is bounded separately.** TUI turns are heavy (per-request cold-boot + long wallclock), so the TUI path has its own limiter — `OCP_TUI_MAX_CONCURRENT` (default `2`), independent of `CLAUDE_MAX_CONCURRENT`. Excess turns queue; a full queue returns a 503. Tune it up only on a host that can run more interactive `claude` sessions at once.
+- **Optional warm pane pool (`OCP_TUI_POOL_SIZE`, default off).** Pre-boots panes so a request skips the cold boot — measured p50 `10.17s` → `6.00s` (−41%). Pooled panes are **single-use** (one turn, then killed and replaced in the background), each carrying its own fresh `--session-id`, so one session still means one exchange and no earlier-turn text can leak into a later answer. They are named `ocp-tui-<port>-p<hex>` and coexist with the reaper by design: the sweep **drains the pool first**, then reaps (so `kill-server` still flushes `<defunct>` zombies), then the pool refills in the background. Drain→reap→resume is synchronous, so no request can land mid-sweep; a request arriving while the pool is still re-booting simply misses it and cold-boots. A live pooled pane is never reaped — **including one that is still booting**, whose tmux session already exists — while an *orphaned* one (left by a previous process generation) still is.
+
+### ⚠️ Latency: TUI mode has a ~6-second floor, and it is immovable
+
+**TUI mode cannot serve real-time or interactive-latency consumers.** This is a hard property of the
+path, stated plainly so you can rule it out before building on it:
+
+| | measured |
+|---|---|
+| **TTFT floor (first token)** | **≈ 6 s** — immovable |
+| cold boot → input bar ready | ~1 s (per request; not the bottleneck) |
+| OCP's own overhead above the CLI | ~4 s (n=1 same-turn decomposition) |
+| direct Anthropic API, same prompt (for scale) | 0.84–1.64 s |
+
+The ~6 s floor is the `claude` CLI itself: it always injects the full Claude Code system prompt plus
+its tool definitions before your prompt, on every turn, no matter what you ask. No flag removes it
+(`--exclude-dynamic-system-prompt-sections` was measured: **no effect** on the floor). Extended
+thinking is *not* the cause — `OCP_TUI_EFFORT` already defaults to `low`, which is what cuts a
+formerly-inherited `xhigh` down to this floor and collapses its variance.
+
+On top of the floor you pay the model's generation time (a function of output length). Progressive
+output is not wired up **yet** (see "No real token streaming" above — it is achievable and planned),
+so today a turn returns as one blob once generation completes. Note that streaming, when it lands,
+will move the *first* byte earlier — it does **not** shorten the turn, and a consumer that needs the
+complete answer gains nothing from it.
+
+**Use TUI mode for**: batch, background, and latency-insensitive work where the subscription pool is
+the point. **Do not use it for**: anything a person is waiting on interactively, or any consumer with
+a sub-5-second budget. Full measurements and methodology:
+[`docs/plans/2026-07-13-tui-latency/`](docs/plans/2026-07-13-tui-latency/).

 ### Monitoring drift via `/health`

@@ -1048,12 +1084,26 @@ Then restart OCP. At boot you will see (with the env token set, isolated home au
  "entrypointMismatches": 0,   // count of cli-expected-but-got-other turns — ALERT if this climbs
  "inflight": 1,               // TUI turns running right now
  "queued": 0,                 // TUI turns waiting for a concurrency slot
-  "maxConcurrent": 2           // OCP_TUI_MAX_CONCURRENT
+  "maxConcurrent": 2,          // OCP_TUI_MAX_CONCURRENT
+  "pool": {                    // warm pane pool — null when OCP_TUI_POOL_SIZE=0 (the default)
+    "size": 2,                 // target warm panes (OCP_TUI_POOL_SIZE)
+    "warm": 2,                 // panes ready right now — each is a LIVE idle claude process
+    "booting": 0,              // replacement panes currently pre-booting
+    "model": "claude-sonnet-4-6", // the model being warmed (the most recently requested one)
+    "hits": 12,                // requests served by a warm pane
+    "misses": 1,               // requests that fell back to the cold boot (the 1st is always one)
+    "boots": 14,               // panes successfully pre-booted
+    "bootFailures": 0,         // pre-boots that genuinely never reached the input bar — WATCH this
+    "cancelled": 4,            // in-flight boots OCP killed on purpose (drain / model switch) — not faults
+    "dropped": 8               // panes discarded unused (drain sweep / expired / unhealthy)
+  }
 }
 ```

 Alert on `entrypointMismatches > 0` (or `lastEntrypoint !== "cli"`): it means a turn drew from the metered Agent SDK pool instead of the subscription. `inflight` / `queued` show how close the TUI path is to its concurrency cap.

+With the pool on, `hits` / `misses` is the hit rate (a steady single-model consumer should sit near 100% after the first request), and `warm` is your standing idle-process cost. A climbing `bootFailures` means panes are not reaching their input bar — the pool then degrades safely to the cold path, but latency reverts to the un-pooled numbers. `cancelled` counts boots OCP killed *on purpose* (a drain, a model switch) and is **not** a fault signal — do not alert on it. A steadily climbing `dropped` is likewise normal: the 15-min reap sweep drains and re-boots the pool on every tick so `kill-server` can still flush `<defunct>` zombies.
+
 ### Kill-switch

 ```bash
@@ -0,0 +1,208 @@
+# ADR 0008 — TUI Warm Pane Pool
+
+**Date:** 2026-07-13
+**Status:** Proposed
+**Extends:** [ADR 0007](0007-tui-interactive-mode.md) (TUI interactive mode). This ADR does not
+change ADR 0007's billing-pool argument, security posture, or kill-switch — it adds a latency
+optimization *inside* the TUI spawn machinery ADR 0007 owns.
+
+---
+
+## Context
+
+TUI mode (ADR 0007) serves every request by cold-booting a fresh `tmux` session running an
+interactive `claude`, submitting one prompt, reading the native transcript, and killing the
+session. That cold boot is paid on **every** request.
+
+[`docs/plans/2026-07-13-tui-latency/`](../plans/2026-07-13-tui-latency/README.md) measured the
+TUI path and listed a warm pane pool as backlog item #3, costed at "**~1.0 s**" (the observed
+boot-to-input-bar time). Instrumenting the real request path showed that estimate is **~4×
+too low**. Phase decomposition of the cold path (n=6 medians, Sonnet 4.6, `--effort low`,
+through a real OCP instance):
+
+| Phase | Median |
+|---|---|
+| prep (trust cwd, write prompt file) | 2 ms |
+| `tmux new-session` | 27 ms |
+| **boot → input bar ready** | **1232 ms** |
+| paste (`load-buffer` + `paste-buffer`) | 8 ms |
+| paste-verify poll | 426 ms |
+| **submit → transcript terminal** | **8458 ms** |
+| teardown | 8 ms |
+| **total** | **10162 ms** |
+| *claude's own reported `turn_duration`* | *5539 ms* |
+| **OCP-side overhead** | **4490 ms** |
+
+The `submit → terminal` phase exceeds claude's own `turn_duration` by **~2.9 s**. That gap is
+**post-input-bar initialization inside `claude`** — work that a pane which has merely *sat idle
+for a few seconds* has already completed. A direct spike confirmed it: an identical pane, idle
+12 s before receiving the same prompt, completed its turn in a median 5537 ms versus 7980 ms
+cold.
+
+So a warm pane recovers **~1.26 s of boot *and* ~2.9 s of in-`claude` cold start** — not the
+~1.0 s the plan predicted.
+
+The reason this was worth a pool rather than a "keep one session and reuse it" cache is a
+hazard already flagged in the code. `lib/tui/transcript.mjs` returns the **last text-bearing
+assistant entry in the whole transcript file**, which is correct *only* under OCP's
+one-session-per-request model, and it says so:
+
+> *"If a future warm-pool ever reuses a session WITHOUT a fresh session-id / clear, earlier-turn
+> text could leak — that author must add user-line scoping here."*
+
+Reusing a pane for a second turn puts two exchanges in one transcript and would leak the earlier
+turn's text into the later turn's answer — a **cross-request data leak**, not merely a bug.
+
+---
+
+## Decision
+
+Add an **opt-in pool of pre-booted, single-use `claude` panes**, `OCP_TUI_POOL_SIZE` (default
+`0` = off, max `4`). Implementation: `lib/tui/pool.mjs`.
+
+### 1. Panes are SINGLE-USE. This is the load-bearing rule.
+
+A pooled pane serves **exactly one turn**, then is killed and replaced in the background. Each
+pane is booted with its **own fresh `--session-id`**, fixed at spawn, and the turn locates its
+transcript by that id.
+
+This preserves one-session-per-request exactly, so the `transcript.mjs` hazard above **does not
+arise** and no user-line scoping was needed. The warning in `transcript.mjs` is deliberately
+left standing, now annotated: it still binds anyone who later wants a pane to serve a second
+turn, or to reset a session with `/clear` and reuse it. **Neither is permitted without first
+adding user-line scoping to the transcript reader.**
+
+Rejected alternative — *reuse a pane for N turns, `/clear` between* — is strictly cheaper
+(no re-boot per request) and was rejected on exactly this basis. The latency win is not worth a
+cross-request text-leak surface guarded only by a `/clear` that we cannot verify landed.
+
+### 2. The pool is keyed by model, and a MISS is always safe.
+
+`--model` is fixed at spawn, so a pane can only serve the model it booted with. A pool miss
+falls back to the existing cold-boot path with **zero behavioural difference**. There is no
+boot-time pre-warm and no configured model: OCP cannot know which model the next caller wants,
+so the pool warms the **most recently requested** model. Consequence, stated plainly: **the
+first request after start, and the first after any model switch, is always a cold miss.**
+
+### 3. The pool and the session reaper coexist by an explicit invariant.
+
+This is the subtle part. `reapStaleTuiSessions()` kills every session matching this instance's
+`ocp-tui-<port>-` prefix, and issues `tmux kill-server` when no foreign session remains (the
+only mechanism that can reap `<defunct>` `claude` zombies — the pane's `claude` is a child of
+the tmux *server*, not of node). A warm pooled pane **is** one of our own sessions, alive and
+idle **by design** — and the periodic sweep runs precisely **when the instance is idle**, i.e.
+exactly when the pool is full.
+
+The invariant, stated in a comment above `reapStaleTuiSessions` and pinned by tests:
+
+1. **A live pooled pane is never reaped — including one that is still BOOTING.** The reaper
+   takes a `spare` set of **exact session names** supplied by the pool's live registry.
+2. **An orphaned pooled pane IS still reaped.** Membership is by **exact name from a live
+   in-memory registry, never by name shape**. A pane the pool no longer owns — handed out,
+   dropped, cancelled, or left behind by a previous process generation (whose registry died with
+   it) — is absent from `spare` and is killed like any other stale session. **Fail-safe:
+   omitting `spare` reaps *more*, never less.** Pool panes are named `ocp-tui-<port>-p<hex>`
+   purely for operator legibility; that shape is *not* the exemption mechanism.
+3. **`kill-server` is suppressed while any pane is spared** (it would kill a live child of the
+   tmux server). Therefore **the pool is DRAINED immediately before every sweep**, so `spare` is
+   empty on the normal tick and `kill-server` still fires. Without the drain, a permanently-full
+   pool would **permanently disable zombie reaping** — the pool would silently break the thing
+   the sweep exists to do. The drain costs one pane re-boot per tick (15 min).
+
+The `spare` mechanism is belt-and-braces given the drain: it makes it impossible for a reap call
+site that *forgets* to drain to kill a live pane.
+
+### 4. The pool tracks its in-flight boot BY NAME, not as a count.
+
+`bootTuiPane` creates the tmux session **synchronously** and only *then* waits (up to
+`POOL_BOOT_MS`, 20 s) for the input bar. So **a pooled tmux session can be live for ~20 s before
+its boot resolves.** A pool that tracked in-flight boots as a *count* could not name that
+session, and this produced two real bugs (both caught in review, both now regression-tested):
+
+- the periodic sweep **killed the booting pane** (it could not be spared), then left the pool
+  empty with nothing scheduled, and logged the exact `tui_pool_boot_failed` warning operators are
+  told to alert on — for a completely healthy drain;
+- graceful shutdown **orphaned a live, authenticated, idle `claude`**: `gracefulShutdown` calls
+  `process.exit(0)` in the same tick as the drain (TUI panes are tmux children, so node's
+  `activeProcesses` set is empty and the "wait for children" path exits immediately), so any
+  cleanup deferred to a `.then()` never ran.
+
+The pool therefore **mints each pane's identity up front** (`{sessionId, name}`, name derived
+from the session-id so `tmux ls` correlates to the transcript file) and holds it in
+`_bootingPane`. `liveNames()` includes it; `drain()` kills it **synchronously**. A generation
+counter distinguishes *"cancelled by us"* from *"genuinely failed"*, so a drain never inflates
+`bootFailures` and `resume()` reliably starts a fresh boot.
+
+### 5. Refills take no concurrency slot, and are serialized.
+
+A refill boot deliberately does **not** take a `TuiSemaphore` slot: those slots bound concurrent
+*turns* and belong to real requests, and charging a background pre-boot against them would let
+the pool starve the traffic it exists to speed up. It cannot leak a slot either, since it never
+holds one. Boots are **serialized** (one at a time): two cold boots racing an in-flight turn were
+observed to overrun even the generous pool readiness cap. A genuinely failed boot does **not**
+re-kick the chain (backoff — a broken `claude` must not respawn forever).
+
+Background boots get a more generous readiness cap (`POOL_BOOT_MS` = 5 × `BOOT_MS`): `BOOT_MS` is
+tight because a *client* is blocked on it, which is not true of a pre-boot. Slow ≠ broken.
+
+---
+
+## Consequences
+
+### Cost — standing processes, paid whether or not a request arrives
+
+**A warm pane is a live idle `claude` process.** Peak process count is
+`OCP_TUI_POOL_SIZE` + `OCP_TUI_MAX_CONCURRENT` + 1 (booting replacement). This is the whole
+reason the pool is **default-off**: an operator must opt into holding processes for traffic that
+may never come. Size is clamped to `POOL_MAX_SIZE` = 4; an unparseable value **disables** the
+pool rather than guessing.
+
+Panes carry a 10-minute TTL and are health-checked at hand-out; a dead or degraded pane becomes
+a **miss** (cold path), never a hung turn.
+
+### Benefit
+
+Measured end-to-end through a real OCP instance (Sonnet 4.6, `--effort low`):
+**p50 10.17 s (n=6, pool off) → 6.00 s (n=12 warm hits) — −4.2 s / −41%.**
+
+### The floor is unchanged
+
+The pool does not touch the **~6 s TTFT floor** documented in the latency plan (claude always
+prefills the full Claude Code system prompt). TUI mode remains unsuitable for interactive /
+real-time consumers; it is for batch and background work. This ADR does not change that
+conclusion.
+
+### Observability
+
+`/health`'s `tui` block gains a `pool` sub-object (`null` when off): `size`, `warm`, `booting`,
+`model`, `hits`, `misses`, `boots`, `bootFailures`, `cancelled`, `dropped`. A climbing
+`bootFailures` means panes are not reaching their input bar — the pool then degrades safely to
+the cold path, but latency reverts to the un-pooled numbers. A steadily climbing `dropped` is
+**normal** (the 15-min sweep drains and re-boots the pool on every tick, by design — see
+Decision 3).
+
+### ALIGNMENT authorization
+
+- **Class B / OCP-owned.** The warm pool is process management around the `claude` CLI — the
+  same category as the existing tmux session lifecycle and the defunct-session reaper it extends.
+  **`cli.js` does not perform this operation, and no `cli.js` citation applies**; the authority
+  is ADR 0007 (which owns the TUI spawn machinery) plus this ADR. This is `ALIGNMENT.md` Rule 2's
+  Class B citation requirement, discharged explicitly rather than by silence.
+- **The `/health` extension** adds sub-fields to the `tui` block. That block is **owned by ADR
+  0007** and post-dates ADR 0006's v3.16.4 grandfather snapshot, so it is not part of the frozen
+  B.2 inventory. The change is additive — every pre-existing `/health` field keeps a
+  byte-identical value, and `pool` is `null` unless the operator opts in — which is the
+  behaviour-preserving bar ADR 0006 sets. This ADR records that authorization.
+- **No spawn argument changed.** `buildTuiCmd` is byte-identical; the pool calls it with the same
+  arguments. Banner-verified on live pooled panes: `· Claude Max`, never `API Usage Billing`
+  (the `--bare` trap documented in the latency plan).
+
+### What a future contributor must not undo
+
+- **Do not let a pane serve a second turn** (or `/clear`-and-reuse one) without first adding
+  user-line scoping to `lib/tui/transcript.mjs`. That is a cross-request text leak, not a perf
+  tweak. See Decision 1.
+- **Do not remove the drain-before-sweep.** It is what keeps `kill-server` zombie reaping alive.
+  See Decision 3.
+- **Do not go back to counting in-flight boots.** The pool must be able to *name* a session that
+  exists but has not finished booting. See Decision 4.
@@ -23,6 +23,8 @@ New ADRs increment from the highest existing number. Filenames are
 | [0004](0004-openclaw-auto-sync.md) | OpenClaw Auto-Sync | Why `scripts/sync-openclaw.mjs` runs on `ocp update`, what its scope boundary is (writes only `models.providers["claude-local"].models` and `agents.defaults.models["claude-local/*"]`), and the idempotency contract. |
 | [0005](0005-no-multi-provider.md) | No Multi-Provider | Why OCP stays single-provider (Anthropic-via-cli.js) and does not extend to OpenAI / Gemini / OpenRouter. Cost estimate: ~7 weeks for a v1 that buys neither moat nor commercial readiness. Separate commercial work starts in a separate repo. |
 | [0006](0006-openai-shim-scope.md) | OpenAI Shim Scope | The Class A / Class B taxonomy. Class A endpoints (`cli.js`-mirror) keep Rules 1–5 verbatim; Class B endpoints (OCP-owned compatibility surface — `/v1/chat/completions`, `/v1/models`, admin endpoints) are anchored to OpenAI's spec (B.1) or to an authorizing ADR (B.2). Triggered by PR #99 (external `response_format` honoring). Grandfathers the existing B.2 inventory at v3.16.4. |
+| [0007](0007-tui-interactive-mode.md) | TUI Interactive Mode | Why TUI-mode spawns an interactive `claude` in a tmux pane (no `-p`) to reach the **subscription** billing pool (`cc_entrypoint=cli`) rather than the metered Agent SDK pool. Owns the TUI spawn machinery: entrypoint labeling, credential-isolated home, MCP hard-disable, session namespace + defunct-session reaping, the independent concurrency bound, and the `/health` `tui` block. **Single-user only** — hard FATAL on multi-user configs. |
+| [0008](0008-tui-warm-pane-pool.md) | TUI Warm Pane Pool | Why `OCP_TUI_POOL_SIZE` pre-boots **single-use** `claude` panes (one turn each, own `--session-id`) — and why reuse is forbidden (`transcript.mjs` returns the last assistant entry in the file, so a reused session leaks the earlier turn's text). Measured −41% end-to-end. Defines the pool↔reaper invariant (exemption by exact name from a live registry; drain before every sweep so `kill-server` zombie reaping survives) and the standing idle-process cost. Extends ADR 0007. |

 ## When to write a new ADR

@@ -0,0 +1,236 @@
+# TUI-mode latency: measured floor, and the four things worth fixing
+
+**Date**: 2026-07-13
+**Status**: findings + backlog. **Superseded in part** — see the dated update boxes below.
+Item #1 shipped ([#156](https://github.com/dtzp555-max/ocp/pull/156)); item #2 is **dead**
+([`streaming-spike.md`](streaming-spike.md)); item #4 measured, **no effect**; item #3 stands.
+**Measured on**: Mac mini / macOS 26.5.2 / Claude Code **v2.1.207** / Sonnet 5 / Claude Max subscription / **real-home mode** (no `CLAUDE_CODE_OAUTH_TOKEN`, no `OCP_TUI_HOME` in the service env)
+**Evidence**: [`measurements.jsonl`](measurements.jsonl) — **n=15** (3 configs × 5) · banner captures [`billing-banner.txt`](billing-banner.txt) · harness [`floor.sh`](floor.sh)
+
+## Why this exists
+
+An external consumer (the 知音 AI project) benchmarked OCP's prompt path and measured
+**TTFT p50 ≈ 30–32 s**, and excluded OCP as a backend on that basis. That number is real,
+but it is *not* the model being slow — this document decomposes where the 30 seconds
+actually go, and what OCP can do about it.
+
+**The harness deliberately does not go through OCP.** It spawns `tmux` + `claude` directly
+(session prefix `zhiyin-floor-`, never `ocp-tui-*`) and polls `tmux capture-pane` for
+incremental render, so it measures the **true first-token time** of the underlying
+subscription path — the floor OCP could reach if it were perfect.
+
+---
+
+## Measurements
+
+All rows in [`measurements.jsonl`](measurements.jsonl); every number below is recomputable from it.
+
+| Config | n | boot→input-ready (median) | **TTFT (median)** | TTFT range | full answer (median) |
+|---|---|---|---|---|---|
+| baseline (inherits global `effortLevel: xhigh`) | 5 | 1.07 s | **10.35 s** | 8.32 – 17.19 s | 11.32 s |
+| **`--effort low`** | 5 | 1.03 s | **6.17 s** | **5.87 – 6.44 s** | 9.98 s |
+| `--bare` | 5 | 0.44 s | **no answer at all** (5/5 `ttft_ms: -1`) | — | — |
+
+> **Not from this harness**: the direct Anthropic API reference figure (TTFT 0.84–1.64 s, n=2)
+> comes from the 知音 AI project's own smoke test, not from `measurements.jsonl`. It is quoted
+> only to size the gap; do not look for it in the evidence file.
+
+### Where the 30 seconds go
+
+```
+ ~1.0 s   spawn → claude's input bar is ready          ← NOT the bottleneck
+ ~6-10 s  true TTFT (first token rendered in the pane)
+ ~20 s    ████ waiting for the whole turn to finish ████  ← this is the 30s
+```
+
+`runTuiTurn` blocks on the native transcript until a terminal event (`lib/tui/session.mjs`
+"Block on the native transcript … until terminal"; `readTuiTranscript` in
+`lib/tui/transcript.mjs`; ADR 0007 step 4) — i.e. it waits for the **entire turn** to complete
+before returning anything. There is no streaming path. The ~20 s delta between this harness's
+real TTFT and OCP's reported 30–32 s is exactly that.
+
+> **⚠️ 2026-07-13 correction — this decomposition attributes the ~20 s to the wrong thing.** It was
+> inferred from the external 30–32 s report, never measured *through* OCP. It has since been measured
+> through a real OCP instance (TUI mode, `claude-sonnet-4-6`, the same ~1850-token prompt, n=5):
+> **median 11.30 s** before [#156](https://github.com/dtzp555-max/ocp/pull/156), **9.55 s** after.
+> Same-turn decomposition (baseline row `i=5`): **11.563 s** wall through OCP vs `turn_duration:
+> 7.319 s` of CLI-internal time on that same turn → **OCP's own overhead ≈ 4.2 s** (n=1), **not
+> ~20 s**. The rest of any larger number is the model *generating a long answer*,
+> which the blocking wait does not cause and streaming would not shorten — it would only move the
+> first byte earlier. The 30–32 s figure therefore reflects a much longer output (and/or the
+> then-inherited `xhigh` effort), not 20 s of OCP dead time. See
+> [`streaming-spike.md`](streaming-spike.md) § "What streaming would have bought".
+
+---
+
+## ⚠️ Blocking constraint: `--bare` silently drops you off the subscription pool
+
+Captured live ([`billing-banner.txt`](billing-banner.txt)) — the startup banner is the **only**
+reliable indicator:
+
+```
+[]                     | Sonnet 5 with xhigh effort · Claude Max
+[--effort low]         | Sonnet 5 with low effort  · Claude Max
+[--bare]               | Sonnet 5 with xhigh effort · API Usage Billing     ← ❌
+```
+
+`--bare` ("skip hooks, LSP, plugin…") **also skips the subscription-credential resolution
+path**. It really does cut boot to 0.43–0.45 s — but you are no longer on the subscription,
+which defeats the entire purpose of TUI mode (ADR 0007 exists solely to reach the
+subscription pool).
+
+**The failure is silent.** All 5 `--bare` samples reached input-ready (boot 0.43–0.45 s), were
+sent the prompt, and then produced **no answer at all** — 60 s timeout, no error, no crash, the
+pane simply never rendered a token (the API-billing account had no credit balance). Nothing in
+the transcript or the exit status reveals this.
+
+**Anyone changing spawn flags must diff the banner line before and after.**
+
+---
+
+## Backlog — four items, ranked by value ÷ effort
+
+### 1. Pass `--effort` explicitly on spawn — **do this first**
+
+`buildTuiCmd` (`lib/tui/session.mjs`) does not pass `--effort` — `grep -rn -- "--effort\|effortLevel" lib/ server.mjs`
+returns zero hits. What the pane's `claude` ends up using therefore depends on **which HOME mode
+`resolveTuiHome()` picked**:
+
+| mode | HOME | effort the pane gets |
+|---|---|---|
+| **real-home** (legacy default — *current* service config: no `CLAUDE_CODE_OAUTH_TOKEN`, no `OCP_TUI_HOME`) | `~` | **inherits the operator's `~/.claude/settings.json` → `effortLevel: xhigh` on this host** |
+| env-token scratch (`CLAUDE_CODE_OAUTH_TOKEN` set — the direction #146/#150 pushed) | `~/.ocp-tui/home` | that settings.json contains only `permissions.additionalDirectories`; `prepareTuiHome()` never writes `effortLevel` → **claude's built-in default** |
+
+**Scope note**: TUI mode is currently *off* on this host (`CLAUDE_TUI_MODE=false`; `/health` →
+`"tui": {"enabled": false}`), so live traffic takes the `-p` path today. The statement below is
+about what happens **when TUI mode is enabled**.
+
+On the current HOME config, **every TUI request would run extended thinking** — pure waste
+for the typical "generate this JSON" request, and it makes latency depend on an unrelated global
+setting the operator may have changed for their own interactive use. And the mode split means
+the effort level silently changes if the operator ever switches to env-token mode.
+**Passing `--effort` explicitly fixes both problems at once.**
+
+- **Effect (real-home, measured)**: TTFT p50 **10.35 s → 6.17 s (−40 %)**, and the spread
+  collapses from 8.32–17.19 s to **5.87–6.44 s**. For a proxy, the variance reduction matters
+  more than the median.
+- **Cost**: one flag. Suggested: a new `OCP_TUI_EFFORT` env var (default `low`), documented in
+  README § "Environment Variables" per `release_kit.new_feature_doc_expectations`.
+- **Risk**: none — banner confirms it stays on `Claude Max` (see `billing-banner.txt`).
+- ⚠️ Do **not** reach for `--bare` to shave boot: see above.
+
+### 2. Real streaming instead of blocking on turn-terminal — **ACHIEVABLE → [`streaming-spike.md`](streaming-spike.md)**
+
+> **2026-07-13 update — the prereq spike was run. The answer is YES, but not from either source this
+> item guessed at.** (a) The transcript grows at *event* granularity (the whole answer lands in one
+> line, ~0.3 s before terminal) — dead. (b) The pane is a **rendered** view whose `capture-pane` text
+> no longer contains the answer's source bytes (`## `, `**`, code fences are gone) — dead, and worse
+> than "lossy": it is *not the model's text*. **But there is a third source neither this backlog nor
+> the first spike considered: `claude` fires a `MessageDisplay` hook carrying incremental,
+> byte-faithful `delta`s of the raw reply.** Verified live on a plain interactive TUI spawn (no `-p`),
+> banner `· Claude Max`: 7 fires spread across generation, `concat(deltas) === T` **byte-exactly**
+> (579 == 579), `T.startsWith(S)` true at every step, `## ` / `**` / ```` ```javascript ```` all
+> present in the deltas. Granularity is block-level (~5–7 chunks/answer), not token-level — plenty for
+> SSE. **Build it.**
+>
+> ⚠️ Two corrections to this item as written: the **"~20 s" is wrong** (inferred from an external
+> report, never measured through OCP — the same-turn decomposition puts OCP's own overhead at **~4 s**,
+> n=1), and **streaming moves the first byte, not the last** — so a consumer needing the *complete*
+> answer (the JSON-card case that motivated this) gains **nothing** from it. Build it for
+> progressively-rendering consumers, not as a throughput win.
+>
+> Full evidence + implementer caveats (the hook is `forceSyncExecution` — claude BLOCKS on it):
+> **[`streaming-spike.md`](streaming-spike.md)**. Original framing preserved below.
+
+Today `runTuiTurn` blocks on the transcript until the turn is *finished*. The pane is already
+rendering tokens incrementally the whole time — this harness proves you can observe first token
+at ~6 s by polling `tmux capture-pane`.
+
+- **Effect**: turns a 30 s wall into a ~6 s TTFT with progressive output; enables SSE streaming
+  on the OCP endpoint instead of a single blob at the end.
+- **Cost**: real work. Pane capture is ANSI/redraw-based and lossy for exact text (wrapping,
+  scrollback, spinner lines). Two candidate sources: (a) incremental reads of the transcript
+  JSONL, (b) `capture-pane` diffing with a stable start marker. (a) is much cleaner **if it
+  holds**.
+- **Prereq spike (do this before designing anything)**: does the transcript JSONL grow *during*
+  a turn, or only at the end? If only at the end, (a) is dead and you are stuck with (b).
+
+### 3. Warm pane pool — ~1 s
+
+Every request spawns a fresh tmux session + `claude` (`randomUUID()` + `new-session`, then
+`kill-session` in `finally`; `grep -rn "pool\|warm\|reuse" lib/tui/*.mjs` → zero hits). Boot to
+input-ready is ~1.0 s, paid on every request. A pool of pre-booted panes (single-use, replaced in
+the background) amortizes it to zero for any workload below the pool refill rate.
+
+- **Effect**: −1.0 s.
+- **Cost**: moderate; interacts with the session reaper and the per-port prefix scoping added in
+  #148 — pooled panes must not look like zombies to the sweep.
+- Lower priority than #1 and #2: it is the smallest slice.
+
+### 4. Trim the prefill — ~~probably not worth it~~ **MEASURED: no detectable benefit. Do not adopt.**
+
+> **2026-07-13 update.** `--exclude-dynamic-system-prompt-sections` was measured with the same
+> harness (`floor.sh`, n=5, Sonnet 5, on top of `--effort low`): **TTFT median 6.39 s**
+> (5.87–10.54 s) vs **6.17 s** (5.87–6.44 s) for `--effort low` alone — i.e. **0.22 s worse, inside
+> the noise band**, with one worse outlier; dropping that outlier does not change the verdict. n=5
+> cannot prove "zero", only "no benefit detectable above noise" — but there is also a **mechanistic**
+> reason not to expect one: `--help` says the flag *"Improves cross-user prompt-cache **reuse**"*, and
+> **OCP is single-user** — there is no cross-user cache to share, so the flag has nothing to buy here.
+> The banner stayed on `· Claude Max` (no billing-pool drop), but there is no win to bank. The ~6 s
+> floor stands as stated below. Raw rows: [`prefill-spike-measurements.jsonl`](prefill-spike-measurements.jsonl).
+
+
+After #1–#3, the floor is **~6 s**, and it does not go lower. `claude` always injects the full
+Claude Code system prompt + tool definitions (thousands to tens of thousands of prefill tokens)
+regardless of what you ask it. `--exclude-dynamic-system-prompt-sections` exists and may shave
+some of it — **unmeasured**; worth one spike, but do not expect to reach the direct API's
+~1 s.
+
+**Consequence to accept, and to state in the README**: even fully optimized, TUI mode has a
+**~6 s TTFT floor**, so it cannot serve real-time / interactive-latency consumers. It remains
+appropriate for batch, background, and cost-insensitive-latency use. The 知音 AI project
+excluded it on this basis (their prompt-latency budget is 2–4 s) *independently* of the ToS
+question already documented in the README.
+
+---
+
+## Reproduction
+
+```bash
+# harness never touches OCP's :3456 service or ocp-tui-* sessions, and never kill-server
+bash docs/plans/2026-07-13-tui-latency/floor.sh 5                                  # baseline
+TAG=effort-low EXTRA_ARGS="--effort low" bash .../floor.sh 5                       # −40 %
+TAG=bare       EXTRA_ARGS="--bare"       bash .../floor.sh 5                       # the trap
+
+# billing-pool check for ANY spawn-flag change — the banner is the only source of truth
+tmux new-session -d -s probe -x 200 -y 50 -c "$HOME" \
+  "claude --model claude-sonnet-5 --session-id $(uuidgen) <your-flags-here>"
+sleep 6; tmux capture-pane -p -t probe | grep -E "Claude Max|API Usage Billing"
+tmux kill-session -t probe
+```
+
+## Interaction with OCP while the harness runs
+
+- **Kill direction is safe both ways**: `reapStaleTuiSessions()` only `kill-session`s names
+  matching `ocp-tui-<port>-`, which `zhiyin-floor-*` never matches; and the harness only
+  `kill-session`s its own single session — it contains **no `kill-server`**.
+- **One benign interaction** (only when TUI mode is enabled — the reap tick is itself gated on
+  `TUI_MODE`): OCP's periodic `kill-server` (zombie reaping) is gated on
+  `othersRemain` — *any* foreign-prefixed tmux session suppresses it. So while the harness is
+  running, that sweep is skipped. This is the coexistence guard working as designed; it resumes
+  on the next tick.
+
+## Harness caveats (stated so the numbers are not over-trusted)
+
+- **n=5 per config**, single host, single model (Sonnet 5), single prompt size (~1850 tokens).
+  Enough to separate 6 s from 10 s from 30 s; **not** enough for a p95.
+- TTFT is "marker visible in `capture-pane`", which includes tmux render latency (small, but
+  nonzero) — it is an upper bound on the true first-token time.
+- **The harness's readiness marker is not OCP's.** `floor.sh` waits for `│ >|❯|Try "`; OCP's
+  `tuiInputReady()` matches `/\? for shortcuts/`. These are different events, so the ~1.0 s
+  boot figure is **not** directly comparable to OCP's `BOOT_MS` gate (default cap 4000 ms). It
+  does not affect the conclusions (1 s ≪ 6 s TTFT), but it is not apples-to-apples.
+- The first version of this harness reported TTFT **0.08 s** — a false positive: the prompt
+  literally contained the marker string it was grepping for, so the match fired the instant the
+  prompt was pasted. Fixed by describing the marker instead of spelling it. **The script exited 0
+  and "successfully" produced 5 samples both times** — exit status proves nothing here.
@@ -0,0 +1,3 @@
+[]                     | ▝▜█████▛▘  Sonnet 5 with xhigh effort · Claude Max
+[--effort low]         | ▝▜█████▛▘  Sonnet 5 with low effort · Claude Max
+[--bare]               | ▝▜█████▛▘  Sonnet 5 with xhigh effort · API Usage Billing
@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# OCP TUI-mode latency floor harness — see README.md in this directory.
+#
+# 目的：回答一个问题——如果把 OCP 现有的两个已知开销砍掉
+#   (a) 每请求 spawn + boot（可用预热进程池消除）
+#   (b) 假流式（等 turn_duration 才返回，可用增量读 pane 消除）
+# 之后，订阅池路径的**真实 TTFT 地板**是多少？
+#
+# 判据：地板 ≤ 4s → OCP 作为"省钱选项"可行；> 8s → 死透，不再讨论。
+#
+# 红线：
+# - 不经过生产 OCP 服务（:3456）—— 直接起 tmux+claude，OCP 进程零干扰
+# - tmux session 前缀用 zhiyin-floor-（**不是** ocp-tui-），避免被 OCP 的
+#   reaper 当成自己的会话杀掉，也避免我们杀到它的
+# - 用 real HOME（凭据）—— scratch HOME + symlink 凭据会 fork OAuth 导致 401
+#   （见跨机记忆 tui_scratch_home_credential_fork）
+set -uo pipefail
+
+N=${1:-5}
+MODEL=${MODEL:-claude-sonnet-5}
+EXTRA_ARGS=${EXTRA_ARGS:-}          # 额外 CLI 参数（如 --effort low --bare）
+TAG=${TAG:-baseline}
+OUT=${OUT:-$(dirname "$0")/measurements.jsonl}
+PROMPT_FILE=$(mktemp)
+PREFIX="zhiyin-floor"
+
+mkdir -p "$(dirname "$OUT")"
+
+# ── 构造提示：~2000 token 的假会议转写 + 明确的起始标记 ────────────────
+# 单行（多行会在 tmux send-keys 时提前触发 Enter）
+build_prompt() {
+  local seg="Speaker A said the quarterly pipeline is tracking behind plan and the enterprise segment needs a different motion. Speaker B replied that the current onboarding flow loses roughly a third of trial accounts before the first integration is complete. They debated whether the fix belongs in product or in customer success. "
+  local body=""
+  for _ in $(seq 1 22); do body+="$seg"; done
+  printf '%s' "You are a real-time meeting copilot. Meeting transcript so far: $body --- Task: produce ONE prompt card as compact JSON with keys: points (array of 3 short Chinese bullet points), keyline (one English sentence the user can read aloud). IMPORTANT: your reply MUST begin with three hash characters immediately followed by the uppercase word CARD (no space between them), then the JSON. No preamble, no markdown fences." > "$PROMPT_FILE"
+}
+build_prompt
+PROMPT_CHARS=$(wc -c < "$PROMPT_FILE" | tr -d ' ')
+
+now_ms() { python3 -c 'import time;print(int(time.time()*1000))'; }
+
+echo "配置: $TAG   参数: [$EXTRA_ARGS]"
+echo "模型: $MODEL   样本: $N   提示长度: ${PROMPT_CHARS} chars (≈$((PROMPT_CHARS/4)) token)"
+echo "输出: $OUT"
+echo
+
+for i in $(seq 1 "$N"); do
+  SESS="${PREFIX}-$$-$i"
+  SID=$(uuidgen)
+
+  # ── 冷启动：spawn + 等输入框就绪 ─────────────────────────────────
+  T_SPAWN=$(now_ms)
+  tmux new-session -d -s "$SESS" -x 200 -y 50 \
+    -e CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 \
+    -e CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 \
+    -c "$HOME" \
+    "claude --model $MODEL --session-id $SID --strict-mcp-config --disallowedTools 'mcp__*' $EXTRA_ARGS" 2>/dev/null
+  if [ $? -ne 0 ]; then echo "[$i] tmux spawn 失败，跳过"; continue; fi
+
+  # 轮询输入框就绪（claude TUI 的输入提示符）
+  READY=0
+  for _ in $(seq 1 150); do   # 上限 15s
+    PANE=$(tmux capture-pane -p -t "$SESS" 2>/dev/null || true)
+    if grep -qE '│ >|❯|Try "' <<<"$PANE"; then READY=1; break; fi
+    sleep 0.1
+  done
+  T_READY=$(now_ms)
+  BOOT_MS=$((T_READY - T_SPAWN))
+  if [ "$READY" -ne 1 ]; then
+    echo "[$i] 启动超时（${BOOT_MS}ms），pane 末 3 行:"
+    tmux capture-pane -p -t "$SESS" 2>/dev/null | tail -3 | sed 's/^/      /'
+    tmux kill-session -t "$SESS" 2>/dev/null
+    continue
+  fi
+
+  # ── 热态：粘提示 → 回车 → 量首 token ─────────────────────────────
+  tmux send-keys -t "$SESS" -l "$(cat "$PROMPT_FILE")" 2>/dev/null
+  sleep 0.4                       # 让粘贴落地（OCP 用 400ms 轮询粒度）
+  T0=$(now_ms)
+  tmux send-keys -t "$SESS" Enter 2>/dev/null
+
+  TTFT_MS=-1
+  for _ in $(seq 1 600); do       # 上限 60s
+    if tmux capture-pane -p -t "$SESS" 2>/dev/null | grep -q '###CARD'; then
+      TTFT_MS=$(( $(now_ms) - T0 )); break
+    fi
+    sleep 0.1
+  done
+
+  # ── 完整回答：pane 连续 2s 不再变化 ──────────────────────────────
+  COMPLETE_MS=-1
+  if [ "$TTFT_MS" -ge 0 ]; then
+    LAST=""; STABLE=0
+    for _ in $(seq 1 900); do     # 上限 90s
+      CUR=$(tmux capture-pane -p -t "$SESS" 2>/dev/null | cksum)
+      if [ "$CUR" = "$LAST" ]; then
+        STABLE=$((STABLE+1))
+        [ "$STABLE" -ge 20 ] && { COMPLETE_MS=$(( $(now_ms) - T0 - 2000 )); break; }
+      else
+        STABLE=0; LAST="$CUR"
+      fi
+      sleep 0.1
+    done
+  fi
+
+  printf '{"i":%d,"tag":"%s","model":"%s","extra_args":"%s","prompt_chars":%s,"boot_ms":%d,"ttft_ms":%d,"complete_ms":%d}\n' \
+    "$i" "$TAG" "$MODEL" "$EXTRA_ARGS" "$PROMPT_CHARS" "$BOOT_MS" "$TTFT_MS" "$COMPLETE_MS" | tee -a "$OUT"
+
+  tmux kill-session -t "$SESS" 2>/dev/null
+  sleep 1
+done
+
+rm -f "$PROMPT_FILE"
+echo
+echo "=== 汇总 ==="
+python3 - "$OUT" <<'EOF'
+import json,sys,statistics
+rows=[json.loads(l) for l in open(sys.argv[1]) if l.strip()]
+ok=[r for r in rows if r['ttft_ms']>=0]
+if not ok: print("无有效样本"); sys.exit()
+def s(k):
+    v=[r[k] for r in ok if r[k]>=0]
+    return f"n={len(v)} 中位={statistics.median(v)/1000:.2f}s 最小={min(v)/1000:.2f}s 最大={max(v)/1000:.2f}s" if v else "无"
+print(f"  冷启动 boot      : {s('boot_ms')}   ← 预热进程池可完全消除")
+print(f"  TTFT（首 token） : {s('ttft_ms')}   ★ 这就是地板")
+print(f"  完整回答         : {s('complete_ms')}")
+print(f"\n  失败样本: {len(rows)-len(ok)}/{len(rows)}")
+EOF
@@ -0,0 +1,15 @@
+{"i": 1, "tag": "effort-low", "model": "claude-sonnet-5", "extra_args": "--effort low", "prompt_chars": 7451, "boot_ms": 1077, "ttft_ms": 6172, "complete_ms": 9929}
+{"i": 2, "tag": "effort-low", "model": "claude-sonnet-5", "extra_args": "--effort low", "prompt_chars": 7451, "boot_ms": 1026, "ttft_ms": 6160, "complete_ms": 9996}
+{"i": 3, "tag": "effort-low", "model": "claude-sonnet-5", "extra_args": "--effort low", "prompt_chars": 7451, "boot_ms": 1010, "ttft_ms": 6437, "complete_ms": 9977}
+{"i": 4, "tag": "effort-low", "model": "claude-sonnet-5", "extra_args": "--effort low", "prompt_chars": 7451, "boot_ms": 1033, "ttft_ms": 5872, "complete_ms": 9944}
+{"i": 5, "tag": "effort-low", "model": "claude-sonnet-5", "extra_args": "--effort low", "prompt_chars": 7451, "boot_ms": 1154, "ttft_ms": 6387, "complete_ms": 9993}
+{"i":1,"tag":"baseline","model":"claude-sonnet-5","extra_args":"","prompt_chars":7451,"boot_ms":1300,"ttft_ms":8321,"complete_ms":9939}
+{"i":2,"tag":"baseline","model":"claude-sonnet-5","extra_args":"","prompt_chars":7451,"boot_ms":1070,"ttft_ms":10347,"complete_ms":11320}
+{"i":3,"tag":"baseline","model":"claude-sonnet-5","extra_args":"","prompt_chars":7451,"boot_ms":911,"ttft_ms":13061,"complete_ms":15163}
+{"i":4,"tag":"baseline","model":"claude-sonnet-5","extra_args":"","prompt_chars":7451,"boot_ms":1441,"ttft_ms":9981,"complete_ms":11066}
+{"i":5,"tag":"baseline","model":"claude-sonnet-5","extra_args":"","prompt_chars":7451,"boot_ms":1036,"ttft_ms":17189,"complete_ms":17985}
+{"i":1,"tag":"bare","model":"claude-sonnet-5","extra_args":"--bare","prompt_chars":7451,"boot_ms":429,"ttft_ms":-1,"complete_ms":-1}
+{"i":2,"tag":"bare","model":"claude-sonnet-5","extra_args":"--bare","prompt_chars":7451,"boot_ms":437,"ttft_ms":-1,"complete_ms":-1}
+{"i":3,"tag":"bare","model":"claude-sonnet-5","extra_args":"--bare","prompt_chars":7451,"boot_ms":444,"ttft_ms":-1,"complete_ms":-1}
+{"i":4,"tag":"bare","model":"claude-sonnet-5","extra_args":"--bare","prompt_chars":7451,"boot_ms":446,"ttft_ms":-1,"complete_ms":-1}
+{"i":5,"tag":"bare","model":"claude-sonnet-5","extra_args":"--bare","prompt_chars":7451,"boot_ms":441,"ttft_ms":-1,"complete_ms":-1}
@@ -0,0 +1,7 @@
+{"hook_event_name": "MessageDisplay", "index": 0, "final": false, "delta": "## Mutex\n\n"}
+{"hook_event_name": "MessageDisplay", "index": 1, "final": false, "delta": "A **mutual exclusion lock** prevents concurrent access to a shared resource, ensuring only one thread runs the critical section at a time.\n\n"}
+{"hook_event_name": "MessageDisplay", "index": 2, "final": false, "delta": "- Acquiring a locked mutex blocks the caller until the current holder releases it.\n"}
+{"hook_event_name": "MessageDisplay", "index": 3, "final": false, "delta": "- Failing to release a mutex causes a deadlock, freezing all waiting threads.\n\n```javascript\nconst { Mutex } = require('async-mutex');\n\nconst mutex = new Mutex();\n"}
+{"hook_event_name": "MessageDisplay", "index": 4, "final": false, "delta": "let counter = 0;\n\nasync function increment() {\n  const release = await mutex.acquire();\n  try {\n"}
+{"hook_event_name": "MessageDisplay", "index": 5, "final": false, "delta": "    counter++; // only one caller here at a time\n  } finally {\n    release();\n  }\n}\n"}
+{"hook_event_name": "MessageDisplay", "index": 6, "final": true, "delta": "```"}
@@ -0,0 +1,5 @@
+{"i":1,"tag":"effort-low-exclude-dynamic","model":"claude-sonnet-5","extra_args":"--effort low --exclude-dynamic-system-prompt-sections","prompt_chars":7451,"boot_ms":934,"ttft_ms":5867,"complete_ms":9953}
+{"i":2,"tag":"effort-low-exclude-dynamic","model":"claude-sonnet-5","extra_args":"--effort low --exclude-dynamic-system-prompt-sections","prompt_chars":7451,"boot_ms":1275,"ttft_ms":6388,"complete_ms":9874}
+{"i":3,"tag":"effort-low-exclude-dynamic","model":"claude-sonnet-5","extra_args":"--effort low --exclude-dynamic-system-prompt-sections","prompt_chars":7451,"boot_ms":874,"ttft_ms":10537,"complete_ms":11782}
+{"i":4,"tag":"effort-low-exclude-dynamic","model":"claude-sonnet-5","extra_args":"--effort low --exclude-dynamic-system-prompt-sections","prompt_chars":7451,"boot_ms":1170,"ttft_ms":6379,"complete_ms":9947}
+{"i":5,"tag":"effort-low-exclude-dynamic","model":"claude-sonnet-5","extra_args":"--effort low --exclude-dynamic-system-prompt-sections","prompt_chars":7451,"boot_ms":1329,"ttft_ms":6443,"complete_ms":9884}
@@ -0,0 +1,256 @@
+# Backlog #2 (real streaming): **achievable** — via the `MessageDisplay` hook
+
+**Date**: 2026-07-13
+**Status**: prereq-spike result. **Streaming IS achievable on the TUI path**, byte-faithfully, on the
+subscription pool. Three obvious sources are dead ends; a fourth one works.
+**Scope**: answers the prereq spike that [`README.md`](README.md) § "Backlog #2" demanded *before* any
+streaming design:
+
+> **Prereq spike (do this before designing anything)**: does the transcript JSONL grow *during* a
+> turn, or only at the end? If only at the end, (a) is dead and you are stuck with (b).
+
+The answer: **(a) is dead, (b) is dead — and you are not stuck with either.** The CLI exposes its own
+streaming interface as a **hook**, which the backlog did not consider.
+
+**Measured on**: Mac mini / Claude Code **v2.1.207** / Sonnet 4.6 + Sonnet 5 / Claude Max /
+real-home mode. Every claim below is reproducible from the commands given.
+
+> **Honesty note on how this document was produced.** Its first version concluded the exact opposite —
+> "streaming is not achievable; the CLI exposes no byte-faithful incremental source" — and was **wrong**.
+> An adversarial reviewer, commissioned specifically to *refute* it, found `MessageDisplay` on a second
+> pass; its own first pass had enumerated the hook registry with a truncated grep (it reported 21
+> events — there are **30**). Both the wrong conclusion and its refutation are preserved here, because
+> "we checked, it's impossible" is the most expensive kind of claim to get wrong: it closes a door and
+> nobody re-opens it.
+
+---
+
+## ✅ The source that works: the `MessageDisplay` hook
+
+`claude` fires a **`MessageDisplay`** hook as it renders each block of the assistant's reply. The
+payload carries the **raw markdown source** of an incremental `delta`, plus a monotonic `index` and a
+`final` flag:
+
+```json
+{ "hook_event_name": "MessageDisplay",
+  "turn_id": "6cb31d21-…", "message_id": "84ab9832-…",
+  "index": 0, "final": false, "delta": "## Mutex\n\n" }
+```
+*(payload also carries `session_id`, `transcript_path`, `prompt_id`, `cwd`)*
+
+Registered as an ordinary command hook via `--settings` on a **plain interactive TUI spawn** (no `-p`,
+no `--bare`), `claude-sonnet-4-6`, `--effort low`. Banner verified:
+`▝▜█████▛▘ Sonnet 4.6 with low effort · Claude Max` — **subscription pool, not metered billing**.
+
+One live turn — 7 fires, spread across generation:
+
+```
+index=0 final=false  len=  10  '## Mutex\n\n'
+index=1 final=false  len= 140  'A **mutual exclusion lock** prevents concurrent access to a shar…'
+index=2 final=false  len=  83  '- Acquiring a locked mutex blocks the caller until the current h…'
+index=3 final=false  len= 163  '- Failing to release a mutex causes a deadlock, freezing all wai…'
+index=4 final=false  len=  96  'let counter = 0;\n\nasync function increment() {\n  const release =…'
+index=5 final=false  len=  84  '    counter++; // only one caller here at a time\n  } finally {\n …'
+index=6 final=true   len=   3  '```'
+```
+
+**Every invariant a proxy needs — all hold:**
+
+| requirement | result |
+|---|---|
+| **byte-faithful** — deltas are the model's *source*, not the rendered pane | ✅ `## `, `**`, ```` ```javascript ```` all present in the deltas |
+| **exactness** — `concat(deltas) === T` (the transcript-authoritative text) | ✅ **true**, 579 == 579 bytes |
+| **prefix-stable** — `T.startsWith(concat(deltas[0..n]))` at every n | ✅ **true at all 7 steps** |
+| **incremental** — arrives during generation, not at the end | ✅ 7 fires spread across the turn |
+| **no `-p`** — stays out of the metered `sdk-cli` pool | ✅ plain interactive TUI |
+| **subscription pool** | ✅ banner `· Claude Max` |
+
+This is exactly the contract a streaming design needs: deltas forward straight into SSE
+`delta.content` chunks, and the transcript's final text `T` stays a cheap end-of-turn assertion
+(`concat === T`) instead of a reconciliation problem.
+
+### Caveats for the implementer
+
+- **Block-level granularity, not token-level** — the hook fires **once per rendered block** (roughly one
+  per paragraph / list item / code block), so the chunk count **scales with answer length**: 7 fires for a
+  ~600-byte answer, **18 for a ~2 KB one**. Plenty for SSE (`delta.content` has no minimum size), but do
+  not promise token-by-token output, and do not hard-code any assumption about chunk count.
+- **🔴 The sink MUST be keyed by `session_id` — this is live TODAY, not a future concern.**
+  `OCP_TUI_MAX_CONCURRENT` defaults to **2**, so **two `claude` processes already run concurrently**. One
+  hook command writing to one shared sink would **interleave deltas from two different turns into one
+  stream** — request A's client receiving request B's text, the worst failure a proxy can have, and one a
+  single-request test will never surface. The payload carries `session_id` (and `turn_id` / `message_id`),
+  so demux is easy: derive the sink path from `session_id` (`<dir>/<session_id>.jsonl`) and read only your
+  own turn's file. This *also* keeps the design **warm-pool compatible**, because a pre-booted pane's
+  session-id is fixed at boot — one static hook script serves every pane. **Test it with ≥2 concurrent
+  streaming requests carrying distinguishable prompts and assert zero cross-contamination.**
+- **⚠️ `forceSyncExecution: true` in the hook's source — `claude` BLOCKS on the hook.** A slow hook
+  adds latency to *every* delta. The hook must write and exit immediately (e.g. write to a FIFO / unix
+  socket that OCP reads; never work inline). **Measure the added per-delta latency.**
+- **Thinking blocks appear to be excluded — but this is NOT yet stress-tested. Verify before shipping.**
+  The exclusion is inferred from `content.map(c => c.type === "text" ? c.text : "")` — but that snippet is
+  from the **`final:true`** call site, not the incremental one. Four live turns (incl. two at `--effort
+  high`) showed no thinking text in any delta and `concat === T` held — **but each transcript's thinking
+  block was empty (`thinking:""`, 0 chars)**, so the exclusion was never actually stressed. **The failure
+  mode is severe**: if thinking deltas *do* fire on some config (Opus, `xhigh`), `concat(deltas) !== T`
+  **and OCP streams the model's private reasoning to the caller**. The end-of-turn `concat === T` assertion
+  would *detect* that but **cannot prevent** it — SSE deltas cannot be un-sent. **Before shipping, run a
+  turn on a model+effort that produces substantive thinking** (a hard reasoning prompt on Opus / `xhigh`)
+  and confirm both (a) no thinking text in any delta and (b) `concat === T` still holds.
+- OCP already owns the spawn (isolated HOME, its own flags), so injecting `--settings` with a
+  `MessageDisplay` hook sits inside the existing architecture.
+- **`ALIGNMENT.md`**: this consumes `claude`'s **own** hook surface as emitted — forwarding, not
+  inventing. Not a new endpoint, not a fabricated protocol. (Class B / ADR 0007 — the TUI spawn is
+  OCP-owned; no `cli.js` citation applies.)
+
+### Reproduce in 60 seconds
+
+```bash
+# hook script: append the payload (arrives on stdin) and exit immediately
+printf '#!/bin/bash\ncat >> "$MD_LOG"; printf "\\n" >> "$MD_LOG"; exit 0\n' > /tmp/h.sh && chmod +x /tmp/h.sh
+echo '{"hooks":{"MessageDisplay":[{"hooks":[{"type":"command","command":"MD_LOG=/tmp/deltas.jsonl /tmp/h.sh"}]}]}}' > /tmp/s.json
+
+# plain interactive claude in tmux (prefix NOT ocp-tui-*, and never kill-server)
+tmux new-session -d -s md-probe -x 220 -y 50 \
+  "claude --model claude-sonnet-4-6 --effort low --session-id $(uuidgen) --settings /tmp/s.json"
+# …wait for '? for shortcuts', paste a markdown-producing prompt, press Enter…
+
+jq -r '"\(.index) \(.final) \(.delta|@json)"' /tmp/deltas.jsonl   # incremental raw-markdown deltas
+# then assert: concat(deltas) == extractLatestAssistantText(<transcript>.jsonl)
+```
+
+---
+
+## The three dead ends (still worth knowing — they say what NOT to build)
+
+### (a) Incremental transcript reads — **dead: event granularity, not token granularity**
+
+The transcript JSONL *does* grow during a turn, but one **whole event at a time**; the assistant's text
+event is written as **one complete line**, appearing only ~0.3 s before the terminal `turn_duration`.
+
+Observed (session `efd5b161`, `turn_duration: 7319 ms`):
+
+```
+ #6  t+0.0s   type=user       (the prompt)
+ #15 t+4.7s   type=assistant  blocks=thinking
+ #16 t+7.0s   type=assistant  blocks=text      ← the ENTIRE answer, in one line
+ #21 t+7.3s   type=system     subtype=turn_duration   ← terminal
+```
+
+Cross-checked at **20 ms polling + `fs.watch`** (25× finer): a partial line **never touches disk** —
+one write, `+1` line, carrying the complete answer. Also forced with the undocumented
+`CLAUDE_CODE_INCLUDE_PARTIAL_MESSAGES=1`: still 1 assistant event, 0 partials (interactive mode has no
+stream-json *sink* for it to write to).
+
+**The transcript is still needed** — as the terminal-turn signal, as the authoritative `concat === T`
+check, and as the input to the existing honesty gates (auth-banner detection, `truncated`). It is just
+not the *streaming* source.
+
+### (b) `tmux capture-pane` diffing — **dead: the pane is a RENDERED view, not the text**
+
+The backlog expected to fall back to this, calling it "lossy … (wrapping, scrollback, spinner lines)".
+The loss is far worse than formatting noise: **the pane does not contain the answer's source bytes at
+all.** The TUI *renders* markdown, and `capture-pane -p` strips the ANSI that rendering produced.
+
+Same turn, same lines:
+
+```
+TRANSCRIPT (authoritative T):          PANE (capture-pane -p -J -S -500):
+  '## Semaphore'                         '⏺ Semaphore'                 ← heading marker gone
+  ''                                     ''
+  'A **semaphore** is a synchro…'        '  A semaphore is a synchro…' ← bold markers gone, indented
+```
+
+| token in the answer | in `T` | in the pane's answer region |
+|---|---|---|
+| `## ` (ATX heading) | yes | **no** — rendered as `⏺` |
+| `**` (bold markers) | yes | **no** — rendered to ANSI bold, then stripped by `-p` |
+| ` ```javascript ` (fence + language) | yes | **no** — fence and language tag both gone |
+| `- ` (list item) | yes | yes |
+
+*(A literal `**` does appear elsewhere in the pane — in the **prompt echo**, because the prompt asked
+for bold. Not in the answer.)*
+
+**`capture-pane -e` (keeping the ANSI) does not rescue it — the inverse is provably non-unique.**
+With `T` = ``"## Alpha\n\n**bravo**\n\n```javascript\nlet x=1;\n```"``:
+
+```
+⏺\e[39m \e[1mAlpha\n\n\e[0m  \e[1mbravo\n\n\e[0m  \e[34mlet\e[39m x=\e[32m1\e[39m;
+```
+
+`## Alpha` → **SGR 1 (bold)**. `**bravo**` → **SGR 1 (bold)**. *Identical ANSI* — an H2 and a bold span
+are indistinguishable, never mind `**` vs `__`. The fence and its `javascript` tag are consumed by the
+syntax highlighter into colours; recovering the tag would mean inverting a highlighter, and
+`let x=1;` is valid in several languages.
+
+So `T.startsWith(paneText)` is **false** — raw and indent-stripped, on essentially every markdown
+answer. A proxy streaming pane text would be streaming **something the model did not say**. With
+`MessageDisplay` available there is no reason to go near it.
+
+### (c) `--debug-file` — **dead: it logs stream *timing*, never stream *content***
+
+Worth stating precisely, because a casual check misleads in **both** directions here.
+
+The default log level is `debug`, which **suppresses every `verbose` site**. Raise it and per-chunk
+lines *do* appear, spread across generation:
+
+```bash
+CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose claude --debug-file /tmp/d.log …
+```
+```
+05:51:11.088 [VERBOSE] [shoji-engine] yield stream_event/-     ← 16 of these, mid-turn,
+05:51:11.537 [VERBOSE] [shoji-engine] yield stream_event/-        over ~3.9 s of generation
+05:51:15.192 [DEBUG]   [shoji-engine] turn 1 end (usage in=575 out=255 api=6736ms stop=end_turn resultLen=857)
+```
+
+**But they carry no payload** — the format is `yield <type>/<subtype>`, a bare presence marker. Run with
+no category filter (i.e. all categories) at verbose level: `content_block_delta` = **0**, `text_delta` =
+**0**, `content_block_start` / `message_start` = **0**. The only byte-exact text in the log is the
+end-of-turn `Stop` hook payload (`"last_assistant_message":"## Title\n\n**alpha bravo charlie**"`) —
+transcript granularity. The log tells you **when** tokens arrive, never **what** they are. It is also
+~2.7 MB per turn.
+
+### Also checked, also not the answer
+
+| candidate | outcome |
+|---|---|
+| `--output-format stream-json` (the one interface that emits `text_delta`) | **requires `--print`/`-p`** → `cc_entrypoint=sdk-cli` → the **metered** credit pool, which is exactly what TUI mode exists to avoid. Reproduced live. |
+| `--input-format stream-json` | `Error: --input-format=stream-json requires output-format=stream-json` → same gate. |
+| `CLAUDE_CODE_INCLUDE_PARTIAL_MESSAGES=1` (undocumented) | No stream-json sink in interactive mode → no partials. Banner stayed `· Claude Max`. |
+| `sessionMirror` (undocumented) | Gated on `outputFormat === "stream-json"` → the `-p` family. |
+| `--sdk-url` (hidden) | Forces stream-json + non-interactive → `sdk-cli`. *(inferred from the minified bundle; not banner-tested)* |
+| `~/.claude/sessions/<pid>.json` | Registry metadata only (`{pid, sessionId, cwd, status, version, entrypoint:"cli", kind:"interactive"}`). No assistant text. *(Its `entrypoint:"cli"` incidentally confirms the TUI path stays on the subscription pool.)* |
+| `~/.claude/history.jsonl` | User prompts only; the answer text is absent. |
+| Asking the model to emit plain text (so the pane renders faithfully) | Would mean **mutating the caller's prompt** — a correctness violation for a proxy, and still not byte-faithful (wrapping + indent remain). Rejected. |
+
+---
+
+## Value: what streaming actually buys (read before building)
+
+Streaming is *possible*. Whether it is *worth it* depends on the consumer, and the honest answer is
+uncomfortable:
+
+- **Streaming never makes the answer arrive sooner. It moves the *first* byte, not the *last*.** The
+  final token lands at the same wall-clock moment either way.
+- So a consumer that must have the **complete** answer before it can act — e.g. one parsing a structured
+  JSON reply, **which is exactly the 知音 AI use case that motivated this entire investigation** — gains
+  **nothing at all**. Only a **progressively-rendering** consumer (a chat UI) gains.
+
+And the number the backlog attached to this item was wrong:
+
+- The backlog's "~20 s" was inferred from an external 30–32 s report, **never measured through OCP**.
+  Measured through a real OCP instance (TUI mode, `claude-sonnet-4-6`, ~1850-token prompt, n=5):
+  **median 11.30 s** before [#156](https://github.com/dtzp555-max/ocp/pull/156), **9.55 s** after.
+- **Same-turn decomposition** (baseline row `i=5`): **11.563 s** wall through OCP vs `turn_duration:
+  7.319 s` of CLI-internal time on that same turn → **OCP's own overhead ≈ 4.2 s** (n=1, baseline
+  `effort=high` config). *Caveats*: n=1; and `turn_duration` is the CLI's internal duration of an
+  **OCP-driven** turn, not a separate "native" baseline. Do **not** subtract this `effort=high` 7.3 s
+  from the `effort=low` 9.55 s median — a low-effort turn generates faster, so mixing them
+  *understates* the overhead.
+- So OCP's own overhead is **single-digit seconds**, not ~20 s. The rest of any large number is the
+  model generating a long answer — which streaming hides but does not shorten.
+
+**Recommendation**: build it — the contract is clean and the cost is small — but size the expectation
+honestly. It is a *perceived-latency* feature for progressively-rendering consumers, not a throughput
+win, and it does not move the **~6 s TTFT floor** ([`README.md`](README.md)) that rules TUI mode out for
+interactive-latency consumers regardless.
@@ -382,11 +382,25 @@ export function getCacheStats() {
 // Per ADR 0005 / spec D4: in-process scope only (single Node process per host).
 const inflightMap = new Map();

-export function singleflight(hash, fn) {
+// `retryIf` (optional, audit finding M1): a predicate applied on the FOLLOWER path only.
+// When a follower joins an existing flight and the shared promise rejects with an error for
+// which retryIf(err) is true (in practice: the LEADER's client disconnected while queued —
+// an error that is personal to the leader, not a verdict about the upstream), the follower
+// does NOT inherit that rejection. Instead it re-enters singleflight with its OWN fn: it
+// either becomes the new leader (the map entry is already deleted — see the finally below,
+// which runs before any follower's catch because it is attached upstream of the promise the
+// followers await) or joins a flight another retrying follower just created. The leader's
+// own rejection is never retried here — its error belongs to it (leader path returns the
+// bare promise). Callers that pass no retryIf get the exact pre-M1 share-everything behavior.
+export function singleflight(hash, fn, retryIf) {
  const existing = inflightMap.get(hash);
  if (existing) {
    existing.requesters++;
-    return existing.promise;
+    if (!retryIf) return existing.promise;
+    return existing.promise.catch((err) => {
+      if (!retryIf(err)) throw err;
+      return singleflight(hash, fn, retryIf);
+    });
  }
  // Wrap fn() in Promise.resolve().then() so synchronous throws don't escape.
  const promise = Promise.resolve().then(fn).finally(() => {
@@ -0,0 +1,67 @@
+// Pure, dependency-injected primitives for the `-p` spawn-token resolution + HOME-isolation
+// layer. Extracted from server.mjs (findings F3 / F5 / F6, 2026-07-07) so the concurrency,
+// caching and expiry logic is unit-testable WITHOUT booting the server or mocking execFileSync /
+// child_process.spawn / fs. server.mjs owns all I/O (macOS keychain exec, process spawn, fs);
+// this module owns only pure decision logic.
+//
+// ALIGNMENT NOTE: none of this touches the OAuth wire machinery (no endpoint / header / body).
+// OCP still NEVER performs a refresh_token grant itself — these helpers only READ + GATE a token
+// that some other process (the operator's real claude, or a spawned claude under the real HOME)
+// refreshes. That property is load-bearing (issue #112) and preserved.
+
+// Promise-chain mutex. `acquire()` resolves to a `release()` fn; the NEXT `acquire()` does not
+// resolve until the current holder calls its `release()`. Serializes async critical sections
+// without busy-waiting. release() is idempotent.
+export function createSerialMutex() {
+  let tail = Promise.resolve();
+  return {
+    acquire() {
+      let release;
+      const gate = new Promise((r) => { release = r; });
+      const prev = tail;
+      tail = tail.then(() => gate);
+      // Hand the caller its release fn only after the previous holder has released.
+      return prev.then(() => {
+        let released = false;
+        return function releaseMutex() { if (!released) { released = true; release(); } };
+      });
+    },
+  };
+}
+
+// Short-TTL memo. `get(produce, now)` returns the cached value while `now - storedAt < ttlMs`,
+// otherwise calls `produce()` and re-stores. A miss that produces null/undefined is STILL stored
+// (so a genuinely-absent source is not re-probed on every call within the TTL window). `now` is
+// injectable for testing.
+export function createTtlCache({ ttlMs }) {
+  let value;
+  let at = -Infinity;
+  let has = false;
+  return {
+    get(produce, now = Date.now()) {
+      if (has && now - at < ttlMs) return value;
+      value = produce();
+      at = now;
+      has = true;
+      return value;
+    },
+    clear() { has = false; value = undefined; at = -Infinity; },
+  };
+}
+
+// Pure expiry gate. Returns true when `creds` carries a known expiry that is at/within `bufferMs`
+// of `now`. Creds WITHOUT `expiresAt` (e.g. long-lived env tokens) are never treated as expiring.
+// This gate is applied to the CACHED creds on EVERY use — which is precisely why a short-TTL
+// keychain cache (createTtlCache) cannot reintroduce the #146 forever-stale-token regression: the
+// cache bounds how often we re-READ the keychain, but the expiry decision is recomputed per use.
+export function isTokenExpiring(creds, now = Date.now(), bufferMs = 300000) {
+  return !!(creds && creds.expiresAt && now + bufferMs >= creds.expiresAt);
+}
+
+// Order candidate keychain labels so the last-known-good label is tried first (avoids the
+// wrong-label miss that doubles the `security` exec count on the hot path). Pure: performs no
+// read. Returns a fresh array; input is not mutated.
+export function orderLabelsLastGoodFirst(labels, lastGood) {
+  if (!lastGood || !labels.includes(lastGood)) return labels.slice();
+  return [lastGood, ...labels.filter((l) => l !== lastGood)];
+}
@@ -0,0 +1,309 @@
+// TUI warm pane pool (docs/plans/2026-07-13-tui-latency backlog #3).
+//
+// WHAT IT IS: a small set of PRE-BOOTED `claude` panes, each already sitting at its
+// input bar, so a request does not pay the cold boot. Opt-in: OCP_TUI_POOL_SIZE=0
+// (default) disables it entirely and the request path is byte-for-byte today's.
+//
+// ── SINGLE-USE IS THE LOAD-BEARING RULE ─────────────────────────────────────
+// A pooled pane serves EXACTLY ONE turn and is then killed and replaced in the
+// background. Each pane carries its OWN fresh `--session-id`, fixed at boot, and the
+// turn locates its transcript by that id. So OCP's one-session-per-request model is
+// preserved: a session's transcript still holds exactly one logical exchange.
+// That is what keeps lib/tui/transcript.mjs's extractLatestAssistantText (which returns
+// the LAST text-bearing assistant entry in the whole file, not "text since the matching
+// user line") correct — see the scoping note there. A pane MUST NEVER serve a second
+// turn, and a session MUST NEVER be reset with /clear and reused: either would put two
+// exchanges in one transcript and leak the earlier turn's text into the later turn's
+// answer. Nothing here reuses a pane; keep it that way.
+//
+// ── WHY IT'S WORTH MORE THAN THE BOOT TIME ──────────────────────────────────
+// Measured on this host (n=6 through OCP, Sonnet 4.6, --effort low): the cold path
+// spends ~1.23 s reaching the input bar, but ALSO ~2.9 s inside the first turn beyond
+// what claude itself reports as the turn duration — post-input-bar init that a pane
+// which has been idle for a few seconds has already finished. A warm pane recovers both.
+//
+// ── COST (bounded, and paid whether or not a request arrives) ───────────────
+// Each warm pane is a LIVE `claude` process (plus its tmux pane) sitting idle. Peak
+// process count is (pool size) + (OCP_TUI_MAX_CONCURRENT in-flight turns) + (panes
+// currently booting as replacements). Pool size is clamped to POOL_MAX_SIZE.
+//
+// Pure + injectable (bootPane / killPane / paneHealthy / now) so test-features.mjs can
+// assert acquire / miss / refill / TTL / reaper-exemption with no tmux and no claude.
+
+// Hard cap on OCP_TUI_POOL_SIZE. Each pane is an idle claude process; 4 is already a
+// lot of resident memory on a small host (a Pi serving a family) for zero in-flight work.
+export const POOL_MAX_SIZE = 4;
+
+// A warm pane older than this is dropped on acquire rather than handed out. The periodic
+// reap tick (server.mjs) drains the pool every 15 min anyway, so this only bites when
+// that tick kept getting skipped because the TUI path was never idle. Guards against
+// handing out a pane whose `claude` has been sitting so long it may have drifted
+// (auto-compaction prompts, an idle-disconnect banner, an expired in-pane token).
+export const POOL_MAX_AGE_MS = 10 * 60 * 1000;
+
+// Clamp the operator-supplied size into [0, POOL_MAX_SIZE]. A garbage value disables the
+// pool rather than guessing — an unparseable size must never silently boot 4 processes.
+export function resolvePoolSize(raw) {
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) return 0;
+  return Math.min(n, POOL_MAX_SIZE);
+}
+
+export class TuiPanePool {
+  // size:       target number of warm panes (0 = disabled).
+  // maxAgeMs:   per-pane TTL (see POOL_MAX_AGE_MS).
+  // mintPane:   () => ({ sessionId, name }) — mints the identity of the NEXT pane. The POOL,
+  //             not the boot function, owns this: the tmux session springs into existence the
+  //             instant bootPane starts, so the pool must already know its NAME (see
+  //             _bootingPane below). Deriving the name from the sessionId also makes `tmux ls`
+  //             correlate to the transcript file.
+  // bootPane:   async (model, {sessionId, name}) => { name, sessionId, model, bootedAt } —
+  //             boots ONE pane under exactly that identity and resolves only once it is
+  //             input-ready; throws if it never becomes ready.
+  // killPane:   (name) => void — tmux kill-session. MUST be synchronous (see drain).
+  // paneHealthy:(name) => bool — pane still exists AND is still at its input bar.
+  constructor({ size, maxAgeMs = POOL_MAX_AGE_MS, mintPane, bootPane, killPane, paneHealthy, now = Date.now, log = () => {} }) {
+    this.size = Math.max(0, Math.min(parseInt(size, 10) || 0, POOL_MAX_SIZE));
+    // Fail fast at CONSTRUCTION, not at request time. refill() is called synchronously from
+    // the request path (runTuiTurn), so a missing collaborator would otherwise surface as a
+    // 500 on a live request instead of a loud error at boot.
+    if (this.size > 0) {
+      for (const [k, fn] of [["mintPane", mintPane], ["bootPane", bootPane], ["killPane", killPane], ["paneHealthy", paneHealthy]]) {
+        if (typeof fn !== "function") throw new TypeError(`TuiPanePool: ${k} must be a function`);
+      }
+    }
+    this.maxAgeMs = maxAgeMs;
+    this._mintPane = mintPane;
+    this._bootPane = bootPane;
+    this._killPane = killPane;
+    this._paneHealthy = paneHealthy;
+    this._now = now;
+    this._log = log;
+
+    this._panes = [];        // warm, available panes: { name, sessionId, model, bootedAt }
+    // The pane currently BOOTING, BY NAME ({sessionId, name, model}) — or null.
+    //
+    // WHY A NAME AND NOT A COUNT (this is a fixed bug, don't regress it): bootTuiPane creates
+    // the tmux session SYNCHRONOUSLY and only THEN waits up to POOL_BOOT_MS (20 s) for the
+    // input bar. So for up to 20 s there is a LIVE pooled tmux session. When the pool tracked
+    // only a count, it could not NAME that session, so:
+    //   - liveNames() could not spare it and the periodic reap sweep KILLED it (and
+    //     kill-server'd on top), leaving the pool empty with nothing scheduled and firing the
+    //     very tui_pool_boot_failed WARN operators are told to alert on; and
+    //   - drain() could not kill it, so on shutdown it ORPHANED a live authenticated `claude`
+    //     (the boot's .then that was supposed to clean up never runs — gracefulShutdown calls
+    //     process.exit in the same tick).
+    // Both are fixed by holding the identity here, before the session exists.
+    this._bootingPane = null;
+    // Generation counter. Bumped whenever an in-flight boot is CANCELLED (drain / model
+    // switch). A boot compares the generation it started under against the current one:
+    // if they differ, its pane was already killed by us and its settle is inert — in
+    // particular a rejection is a CANCELLATION, not an operator-visible boot failure.
+    this._gen = 0;
+    this._paused = false;    // true while drained; refill() is a no-op until resume()
+    this.warmModel = null;   // the model the pool currently warms — learned from traffic (see acquire)
+
+    this.hits = 0;           // requests served by a warm pane
+    this.misses = 0;         // requests that fell back to the cold path
+    this.boots = 0;          // panes successfully pre-booted
+    this.bootFailures = 0;   // pre-boots that genuinely never reached the input bar
+    this.cancelled = 0;      // in-flight boots WE killed (drain / model switch) — not failures
+    this.dropped = 0;        // panes discarded unused (unhealthy / expired / wrong model / drained /
+                             // cancelled — a cancelled in-flight boot also lands here via _drop)
+  }
+
+  get enabled() { return this.size > 0; }
+  get warm() { return this._panes.length; }
+  get booting() { return this._bootingPane ? 1 : 0; }
+
+  // The reaper's spare set: the EXACT names of every pane the pool currently owns and has NOT
+  // handed out — the warm ones AND the one currently booting (whose tmux session is already
+  // live; see _bootingPane). See the POOL/REAPER INVARIANT in lib/tui/session.mjs.
+  // Fail-safe by construction: a pane leaves this set the instant it is acquired, dropped, or
+  // cancelled, and if the pool is empty (or the process restarted) the set is empty — so an
+  // orphaned pooled pane looks exactly like any other stale session and IS reaped.
+  liveNames() {
+    const names = new Set(this._panes.map((p) => p.name));
+    if (this._bootingPane) names.add(this._bootingPane.name);
+    return names;
+  }
+
+  // Take a warm pane for `model`, or null (caller must fall back to the cold path — a MISS
+  // is always safe, never an error). Synchronous: paneHealthy is a cheap tmux capture.
+  //
+  // The pool warms the MOST RECENTLY REQUESTED model (`warmModel`). There is no boot-time
+  // pre-warm and no configured model: OCP cannot know which model the next caller wants, and
+  // pre-booting a process for a model nobody asks for is pure waste. Consequence, stated
+  // plainly: the FIRST request after start (and the first after a model switch) is always a
+  // MISS. The pool pays off for the steady repeat traffic it exists to serve.
+  acquire(model) {
+    if (!this.enabled) return null;
+
+    // Retarget on a model switch: --model is fixed at spawn, so panes for another model are
+    // useless. Drop them now (they are replaced by the next refill) rather than holding
+    // processes for a model that is no longer being asked for. This includes any pane
+    // currently BOOTING for the old model — its tmux session already exists, so leaving it to
+    // die on resolve would both hold a useless process and block the next refill (one boot at
+    // a time) for up to POOL_BOOT_MS.
+    if (model !== this.warmModel) {
+      for (const p of this._panes) { this._drop(p, "model_switch"); }
+      this._panes = [];
+      this._cancelBooting("model_switch");
+      this.warmModel = model;
+    }
+
+    while (this._panes.length) {
+      const p = this._panes.shift();
+      if (this._now() - p.bootedAt > this.maxAgeMs) { this._drop(p, "expired"); continue; }
+      if (!this._paneHealthy(p.name)) { this._drop(p, "unhealthy"); continue; }
+      this.hits++;
+      return p; // caller OWNS it now: it is out of the registry (so out of the spare set),
+                // and the caller's finally MUST kill it. Single-use — never returned here.
+    }
+    this.misses++;
+    return null;
+  }
+
+  // Bring the pool back up to `size` warm panes for `warmModel`. Fire-and-forget: never
+  // awaited on the request path and never throws into it.
+  //
+  // SLOT ACCOUNTING: a refill boot deliberately does NOT take a TuiSemaphore slot. Those
+  // slots bound concurrent *turns* (each up to the 120 s wallclock) and belong to real
+  // requests; charging a background pre-boot against them would let the pool starve the
+  // traffic it exists to speed up. It cannot leak a slot either, because it never holds one.
+  //
+  // SERIALIZED, ONE BOOT AT A TIME (and re-kicked on success until the pool is at target).
+  // An earlier version launched all `want` boots at once; live at size=2 that put two cold
+  // `claude` boots plus an in-flight turn on the CPU together, and a refill overran even the
+  // generous pool readiness cap (tui_pool_boot_failed). Booting sequentially keeps each boot
+  // near its uncontended ~1.2 s, bounds the CPU burst the pool can cause, and still has the
+  // replacement pane warm long before the next request arrives.
+  //
+  // A genuinely FAILED boot deliberately does NOT re-kick the chain — that is the backoff. A
+  // persistently failing boot (bad claude binary, no auth) would otherwise spin, respawning
+  // forever. The next natural trigger (the following request's refill, or the reap tick's
+  // resume) retries it. A CANCELLED boot is different: we killed it on purpose, nothing is
+  // wrong, and resume() is expected to start a fresh one immediately.
+  refill() {
+    if (!this.enabled || this._paused || !this.warmModel) return;
+    if (this._bootingPane) return;                       // one boot in flight at a time
+    if (this._panes.length >= this.size) return;         // already at target
+
+    const model = this.warmModel;
+    const gen = this._gen;
+    // Mint the identity BEFORE booting: bootPane creates the tmux session synchronously, so
+    // the pool must be able to name (and therefore spare, and kill) it from this moment on.
+    const ident = this._mintPane();
+    this._bootingPane = { ...ident, model };
+    let enlisted = false;
+    Promise.resolve()
+      .then(() => this._bootPane(model, ident))
+      .then((pane) => {
+        // The world may have moved while we booted. If our generation was cancelled, kill the
+        // pane here rather than ASSUMING _cancelBooting already did.
+        //
+        // Why not just `return`: _cancelBooting kills by name, but the tmux session only EXISTS
+        // once _bootPane has actually run — and _bootPane is queued on a microtask (above). A
+        // caller that does refill() and then drain() in the SAME synchronous block would have
+        // _cancelBooting find nothing to kill (a no-op), bump the generation, and then this
+        // microtask would create the session, boot it fine, and — under a bare `return` — walk
+        // away from a LIVE authenticated `claude` that nothing owns. That is M1b in a new costume.
+        // No current call site does that, so this is defense-in-depth, not a live bug — but ADR
+        // 0008 and the reap-tick comment in server.mjs both explicitly contemplate a boot-time
+        // pre-warm, which is exactly the shape that would reach it.
+        //
+        // Killing an already-dead session is a harmless no-op (_drop swallows it), so this is
+        // idempotent whether or not _cancelBooting got there first.
+        if (gen !== this._gen) { this._drop(pane, "cancelled_late"); return; }
+        // Otherwise: still possible the pool filled or retargeted without a cancellation.
+        if (this._paused || model !== this.warmModel || this._panes.length >= this.size) {
+          this._drop(pane, "stale_boot");
+          return;
+        }
+        this._panes.push(pane);
+        this.boots++;
+        enlisted = true;
+      })
+      .catch((e) => {
+        // A rejection from a CANCELLED generation is not a fault: it is almost always
+        // "tui_pane_not_ready", thrown because WE killed the pane out from under the boot.
+        // Counting it as a bootFailure would fire the exact WARN operators are told to alert
+        // on, for a completely healthy drain. Stay silent — _cancelBooting already counted
+        // this as a cancellation, so do NOT count it again here.
+        if (gen !== this._gen) return;
+        this.bootFailures++;
+        this._log("warn", "tui_pool_boot_failed", { model, error: e && e.message });
+      })
+      .finally(() => {
+        // ONLY the current generation's boot owns the booting slot. A stale settle must not
+        // clear a slot that a newer boot (started by resume()) already holds.
+        if (gen === this._gen) this._bootingPane = null;
+        if (enlisted) this.refill(); // continue toward target, still one at a time
+      });
+  }
+
+  // Kill the in-flight boot's pane, SYNCHRONOUSLY, and invalidate its generation. Returns 1
+  // if there was one, else 0. The tmux session already exists (bootPane created it before it
+  // started waiting for readiness), so this is a real kill, not a cancellation flag.
+  _cancelBooting(reason) {
+    if (!this._bootingPane) return 0;
+    this._gen++;                              // the in-flight boot's settle is now inert
+    this._drop(this._bootingPane, reason);    // synchronous kill-session
+    this._bootingPane = null;
+    this.cancelled++;
+    return 1;
+  }
+
+  // Kill every pane the pool owns — warm AND currently booting — and stop refilling. Returns
+  // how many were killed.
+  //
+  // Called (a) before the periodic reap sweep — reapStaleTuiSessions can only reap defunct
+  // `claude` zombies via kill-server, and kill-server is suppressed while any live pooled pane
+  // exists (including a booting one), so without this drain the pool would permanently disable
+  // zombie reaping; and (b) on graceful shutdown, so no pane outlives the process as an orphan.
+  //
+  // EVERY KILL HERE IS SYNCHRONOUS, and that is load-bearing. It is NOT safe to leave the
+  // booting pane to clean itself up on resolve: gracefulShutdown calls process.exit() in the
+  // same tick as this drain (TUI panes are children of the tmux SERVER, not of node, so
+  // node's activeProcesses set is empty on a TUI host and the "wait for children" path exits
+  // immediately). A .then()/.catch() scheduled here would never run, and the pane would
+  // survive as an orphaned, authenticated, idle `claude`.
+  drain() {
+    this._paused = true;
+    let n = this._panes.length;
+    for (const p of this._panes) this._drop(p, "drain");
+    this._panes = [];
+    n += this._cancelBooting("drain_booting");
+    return n;
+  }
+
+  // Undo drain() and start refilling again. Because drain() CANCELLED the in-flight boot
+  // (rather than leaving it pending), the booting slot is free and this really does start a
+  // fresh boot — the pool is never left empty with nothing scheduled.
+  resume() {
+    this._paused = false;
+    this.refill();
+  }
+
+  // /health surface (additive).
+  stats() {
+    return {
+      size: this.size,
+      warm: this._panes.length,
+      booting: this.booting,
+      model: this.warmModel,
+      hits: this.hits,
+      misses: this.misses,
+      boots: this.boots,
+      bootFailures: this.bootFailures,
+      cancelled: this.cancelled,
+      dropped: this.dropped,
+    };
+  }
+
+  _drop(pane, reason) {
+    this.dropped++;
+    try { this._killPane(pane.name); } catch { /* already gone */ }
+    this._log("info", "tui_pool_pane_dropped", { name: pane.name, reason });
+  }
+}
@@ -20,6 +20,15 @@
 //
 // Pure + importable so test-features.mjs can assert the bound directly (no server boot).

+// Thrown by acquire() when the caller-supplied AbortSignal fires before a slot was granted
+// (audit finding F2 — a client that disconnects while queued must never receive a slot; the
+// queue entry is spliced out, not just flagged, so `queued` accounting stays exact). Distinct
+// `name` lets callers (server.mjs acquireClaudeSlot) tell "client went away" apart from
+// "queue is full" without string-matching the message.
+export class SemaphoreAbortError extends Error {
+  constructor(message) { super(message); this.name = "SemaphoreAbortError"; }
+}
+
 export class TuiSemaphore {
  // limit: max concurrent slots. maxQueue: max waiters before run() rejects with backpressure.
  constructor(limit, { maxQueue } = {}) {
@@ -34,9 +43,30 @@ export class TuiSemaphore {
  get inflight() { return this._inflight; }
  get queued() { return this._waiters.length; }

+  // Runtime-adjust the concurrency limit (audit finding F1 — a PATCH /settings maxConcurrent
+  // change must actually take effect, not just be ignored until every currently-inflight task
+  // happens to finish). Lowering the limit is handled lazily by release() (see below) — it
+  // simply stops re-granting until inflight drains under the new, lower limit. Raising the
+  // limit has immediate headroom, so we wake as many queued waiters as now fit.
+  setLimit(limit) {
+    this.limit = Math.max(1, parseInt(limit, 10) || 1);
+    while (this._inflight < this.limit && this._waiters.length > 0) {
+      const next = this._waiters.shift();
+      this._inflight++;
+      next();
+    }
+  }
+
  // Acquire a slot. Resolves once a slot is free (immediately if under the limit, otherwise
  // when an in-flight task releases). Rejects synchronously-ish if the wait queue is full.
-  acquire() {
+  // `signal` (optional AbortSignal, F2) lets the caller cancel a QUEUED wait — e.g. wired to
+  // a client's socket "close" event so a request that disconnects before a slot is granted
+  // is removed from the queue instead of eventually being handed a slot for a dead socket.
+  // If `signal` is already aborted, reject immediately without ever touching the queue.
+  acquire(signal) {
+    if (signal?.aborted) {
+      return Promise.reject(new SemaphoreAbortError("acquire aborted before requesting a slot"));
+    }
    if (this._inflight < this.limit) {
      this._inflight++;
      return Promise.resolve();
@@ -46,24 +76,44 @@ export class TuiSemaphore {
        `tui_queue_full: TUI concurrency limit (${this.limit}) reached and wait queue ` +
        `(${this.maxQueue}) is full`));
    }
-    return new Promise((resolve) => { this._waiters.push(resolve); });
+    return new Promise((resolve, reject) => {
+      let waiter; // the FIFO entry — captured so onAbort can find + splice exactly this one
+      const onAbort = () => {
+        const idx = this._waiters.indexOf(waiter);
+        if (idx === -1) return; // already granted a slot (shifted out by release()/setLimit) — too late to cancel
+        this._waiters.splice(idx, 1); // remove, not just flag — keeps `queued` accounting exact
+        reject(new SemaphoreAbortError("acquire aborted while queued"));
+      };
+      waiter = () => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      this._waiters.push(waiter);
+    });
  }

-  // Release a slot. If a waiter is queued, hand the slot directly to it (inflight stays
-  // constant across the handoff); otherwise decrement.
+  // Release a slot. Always frees the caller's own slot first, then re-grants it to the next
+  // waiter ONLY if the (post-decrement) inflight count is still under the current limit (F1
+  // fix). This is what makes a runtime-lowered limit actually bite: if the limit was lowered
+  // while over-subscribed, releases stop re-granting and inflight drains toward the new limit
+  // instead of a freed slot being handed straight back out at the old, higher occupancy.
  release() {
-    const next = this._waiters.shift();
-    if (next) {
-      next(); // the woken waiter already "owns" the slot — inflight unchanged
-    } else if (this._inflight > 0) {
-      this._inflight--;
+    if (this._inflight > 0) this._inflight--;
+    if (this._inflight < this.limit) {
+      const next = this._waiters.shift();
+      if (next) {
+        this._inflight++;
+        next();
+      }
    }
  }

  // Run fn() under one slot. Releases in a finally so a throw (PR-A's honesty gates,
  // wallclock truncation, paste-not-landed, tmux spawn failure) NEVER leaks a slot.
-  async run(fn) {
-    await this.acquire();
+  // `signal` (optional, F2) is forwarded to acquire() so a queued run() can be cancelled.
+  async run(fn, signal) {
+    await this.acquire(signal);
    try {
      return await fn();
    } finally {
@@ -89,7 +139,12 @@ export function recordTuiEntrypoint(tuiStats, observed, expectedMode = "cli") {
 // Build the additive /health `tui` block (ADR 0007 PR-B amendment). Pure: given the
 // config + live counters, returns the exact object embedded in /health. New fields only —
 // behaviour-preserving for existing /health consumers (grandfathered B.2 under ADR 0006).
-export function buildTuiHealthBlock({ enabled, entrypointMode, maxConcurrent }, tuiStats, semaphore) {
+//
+// `pool` (optional, warm pane pool — lib/tui/pool.mjs): a TuiPanePool, or null/undefined
+// when the pool is off (the default). Reported as `pool: null` when off so the block's
+// shape stays stable, and as the pool's stats (size / warm / hits / misses / …) when on —
+// the operator's window onto both the hit rate and the standing idle-process cost.
+export function buildTuiHealthBlock({ enabled, entrypointMode, maxConcurrent }, tuiStats, semaphore, pool = null) {
  return {
    enabled,
    entrypointMode,                                  // cli | auto | off
@@ -98,5 +153,6 @@ export function buildTuiHealthBlock({ enabled, entrypointMode, maxConcurrent },
    inflight: semaphore.inflight,                    // current concurrent TUI turns
    queued: semaphore.queued,                        // turns waiting for a slot
    maxConcurrent,
+    pool: pool ? pool.stats() : null,                // warm pane pool, or null when disabled
  };
 }
@@ -15,14 +15,48 @@ import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { readTuiTranscript } from "./transcript.mjs";

-export const SESSION_PREFIX = "ocp-tui-"; // per-proxy namespace (coexistence rule)
+// F7 fix (audit finding, LOW): the prefix used to be a bare, host-wide constant
+// ("ocp-tui-"), so a SECOND OCP instance on the same host (e.g. a temporary
+// verification instance stood up alongside production — a real pattern used during
+// PR #144/#146 verification) would boot-reap and potentially kill-server the OTHER
+// instance's LIVE sessions: the coexistence guard below only ever spared foreign
+// PRODUCT prefixes (olp-tui-*), never a second ocp-tui-* instance on a different port.
+//
+// Fix: scope the prefix to the instance's own listen port. The port is the natural
+// stable per-instance discriminator on one host (two OCP instances cannot share a
+// port), so `ocp-tui-<port>-` uniquely namespaces this instance's sessions and makes
+// a same-host sibling OCP instance look exactly like a foreign product (olp-tui-*) to
+// the coexistence guard — its `ocp-tui-<otherPort>-*` sessions never match our own
+// prefix and are therefore never reaped/kill-server'd by us.
+//
+// LEGACY_SESSION_PREFIX / LEGACY_SESSION_NAME_RE describe the OLD bare-prefix shape
+// (pre-this-fix), retained ONLY for the boot-time legacy-zombie migration handled in
+// reapStaleTuiSessions (see comment there). No code path in this version ever CREATES
+// a legacy-shaped session name again — sessionPrefixForPort() is the only session-name
+// prefix constructor used going forward.
+export const LEGACY_SESSION_PREFIX = "ocp-tui-";
+// Exact legacy shape: LEGACY_SESSION_PREFIX + sessionId.slice(0, 8), where sessionId is
+// a randomUUID() — so the suffix is always exactly 8 lowercase hex characters with NO
+// further separator. The new port-scoped shape always inserts a "-" between the port
+// digits and the 8-hex suffix (see sessionPrefixForPort), so this regex can never match
+// a new-shape name: a new-shape suffix is `<port digits>-<8 hex>` (contains a literal
+// "-"), which `[0-9a-f]{8}$` anchored immediately after the prefix cannot satisfy.
+export const LEGACY_SESSION_NAME_RE = /^ocp-tui-[0-9a-f]{8}$/;
+
+// Build this instance's own session-name prefix, scoped by its listen port so a
+// second OCP instance on the same host (different port) is never mistaken for "ours".
+export function sessionPrefixForPort(port) {
+  return `ocp-tui-${port}-`;
+}
+
 const TMUX = process.env.OCP_TUI_TMUX_BIN || "tmux";

 const defaultTmux = (args, opts = {}) =>
  spawnSync(TMUX, args, { encoding: "utf8", ...opts });

-// Kill ONLY our own stale sessions. Scoped to SESSION_PREFIX so a co-hosted
-// OLP test instance's `olp-tui-*` sessions are never touched.
+// Kill ONLY our own stale sessions. Scoped to sessionPrefixForPort(port) so a co-hosted
+// OLP test instance's `olp-tui-*` sessions — AND a co-hosted second OCP instance's
+// `ocp-tui-<otherPort>-*` sessions — are never touched (F7 fix).
 //
 // Defunct-reaping (PI231 incident): the pane's `claude` process is a child of the
 // long-lived tmux SERVER daemon, NOT of the OCP node process — `tmux new-session -d`
@@ -36,29 +70,86 @@ const defaultTmux = (args, opts = {}) =>
 // merely re-signalling — is to stop the tmux server: when the server exits, the kernel
 // reparents its surviving children to init (PID 1), which reaps them immediately.
 //
-// So after killing our own sessions, if the server has NO sessions left of ANY prefix
-// (i.e. nothing we could disrupt — no co-hosted `olp-tui-*` or other instance), we
-// `kill-server` to flush the defunct backlog. If ANY non-ocp session remains we leave the
-// server running (coexistence rule, ADR 0007) and let the next boot/periodic sweep retry
-// once the server is otherwise idle.
-export function reapStaleTuiSessions({ tmux = defaultTmux } = {}) {
+// `port` (required) is this instance's own listen port (server.mjs's PORT / lib/constants.mjs
+// DEFAULT_PORT resolution) — the SPOT for "which sessions are ours."
+//
+// ── POOL/REAPER INVARIANT (warm pane pool — lib/tui/pool.mjs) ───────────────────────────
+// A warm pooled pane is one of OUR OWN `ocp-tui-<port>-*` sessions that is ALIVE AND IDLE
+// BY DESIGN — and the periodic sweep runs precisely when the instance is idle, i.e. exactly
+// when the pool is full. Without an exemption the sweep would kill every warm pane on every
+// tick (and kill-server on top). The exemption is `spare`: a set of EXACT session names the
+// caller declares live. Three properties, all load-bearing:
+//
+//   1. A LIVE POOLED PANE IS NEVER REAPED — INCLUDING ONE THAT IS STILL BOOTING. It is in
+//      `spare` (the pool's live registry), so it is skipped by name. The booting case is not
+//      a footnote, it is the one that bit us: bootTuiPane creates the tmux session
+//      SYNCHRONOUSLY and only then waits up to POOL_BOOT_MS for the input bar, so a pooled
+//      session can be live for ~20 s before its boot resolves. The pool therefore mints the
+//      pane's NAME up front and holds it in `_bootingPane`, so liveNames() can name — and
+//      spare — a session whose boot has not finished. (An earlier version tracked only a
+//      COUNT of in-flight boots; the sweep could not name that session and killed it.)
+//   2. A LEAKED/ORPHANED POOLED PANE IS STILL REAPED. Membership is by EXACT NAME from a
+//      live in-memory registry — NOT by "looks pooled" (name shape). A pane the pool no
+//      longer owns (handed out, dropped, cancelled, or left behind by a previous process
+//      generation — whose registry died with it) is absent from `spare` and is killed like
+//      any other stale session. Fail-safe: forgetting to pass `spare` reaps MORE, never less.
+//   3. KILL-SERVER NEVER KILLS A LIVE POOL PANE. A spared session suppresses kill-server
+//      exactly as a foreign session does (it is a live child of the tmux server). The
+//      consequence — that a permanently-full pool would permanently disable the defunct-
+//      zombie reaping that ONLY kill-server can do — is resolved in server.mjs by DRAINING
+//      the pool immediately before the sweep, so `spare` is empty on the normal tick and
+//      kill-server still fires. `spare` is the belt-and-braces: a reap call site that
+//      forgets to drain still cannot kill a live pane.
+//
+// `spare` (default: none) — iterable of session names, or a Set. Ignored when the pool is off.
+//
+// `includeLegacy` (default false): when true, sessions matching the exact OLD bare-prefix
+// shape (LEGACY_SESSION_NAME_RE) are ALSO treated as ours for kill-session purposes. This is
+// the boot-time legacy migration: an operator upgrading past this fix could otherwise be left
+// with orphaned bare-prefix zombie sessions from the PREVIOUS (pre-fix) process generation of
+// this SAME instance, since no live instance of the new version ever creates that shape again
+// — a legacy-shaped session found at boot is therefore presumed to be this instance's own
+// leftover, not a stranger's. Passed true ONLY from the one-time boot-reap call site in
+// server.mjs; the periodic idle-reap sweep does NOT set it, so a lingering legacy session
+// during steady-state is conservatively treated as foreign (correctly blocking kill-server)
+// rather than assumed to be ours on every 15-minute tick. Residual (accepted, documented):
+// if a genuinely-still-running PRE-FIX OCP instance is coexisting on the same host at the
+// exact moment a new instance boots, its live legacy-shaped session could be reaped — the
+// same class of residual risk the audit finding itself accepts ("no live instance of the new
+// version creates them"); this PR does not regress that scenario, it only removes the far
+// more common same-version collision (the actual F7 finding).
+export function reapStaleTuiSessions({ tmux = defaultTmux, port, includeLegacy = false, spare = null } = {}) {
  const r = tmux(["list-sessions", "-F", "#{session_name}"]);
  if (!r || r.status !== 0) return 0; // no tmux server / no sessions
  const names = String(r.stdout || "").split("\n").map((s) => s.trim()).filter(Boolean);
+  const ownPrefix = sessionPrefixForPort(port);
+  const spared = spare instanceof Set ? spare : new Set(spare || []);
  let killed = 0;
  let othersRemain = false;
+  let sparedLive = 0;
  for (const name of names) {
-    if (name.startsWith(SESSION_PREFIX)) {
+    // Property 1+2: exemption is by EXACT NAME from the pool's live registry. A pooled-
+    // LOOKING name that is not in the registry is an orphan and falls through to the
+    // normal kill path below.
+    if (spared.has(name)) { sparedLive++; continue; }
+    const isOwn = name.startsWith(ownPrefix);
+    const isLegacyOwn = includeLegacy && LEGACY_SESSION_NAME_RE.test(name);
+    if (isOwn || isLegacyOwn) {
      tmux(["kill-session", "-t", name]);
      killed++;
    } else {
-      othersRemain = true; // a session we do NOT own (e.g. olp-tui-*) — never kill-server
+      othersRemain = true; // a session we do NOT own (olp-tui-*, a sibling ocp-tui-<otherPort>-*,
+                            // or — outside includeLegacy — a legacy-shaped name) — never kill-server
    }
  }
  // Reap defunct `claude` zombies: safe ONLY when the server is now ours-only/empty.
  // kill-server is what actually reaps (server exit reparents survivors to init); a
  // per-session kill cannot, since node is not the zombies' parent.
-  if (!othersRemain) {
+  //
+  // Property 3: a SPARED session is a live child of this tmux server, so kill-server would
+  // kill it — it therefore suppresses kill-server exactly as a foreign session does. On the
+  // normal sweep the pool is drained first, so sparedLive is 0 and kill-server still fires.
+  if (!othersRemain && sparedLive === 0) {
    tmux(["kill-server"]);
  }
  return killed;
@@ -68,6 +159,12 @@ export function reapStaleTuiSessions({ tmux = defaultTmux } = {}) {

 // Boot + paste-settle timing. Conservative defaults validated on PI231; env-tunable.
 const BOOT_MS         = parseInt(process.env.OCP_TUI_BOOT_MS  || "4000", 10);   // max wait for input-ready
+// Readiness cap for a POOL pre-boot. Deliberately far more generous than BOOT_MS: BOOT_MS is
+// tight because a client is blocked on it, whereas a warm-pane boot happens in the background
+// with nobody waiting. Observed live at size=2: a refill booting alongside an in-flight turn
+// exceeded 4000 ms and was discarded (tui_pool_boot_failed), quietly costing hit rate for a
+// pane that was merely slow, not broken. Scales with OCP_TUI_BOOT_MS if an operator raises it.
+export const POOL_BOOT_MS = BOOT_MS * 5;
 const READY_POLL_MS   = parseInt(process.env.OCP_TUI_READY_POLL_MS || "400", 10); // readiness / paste-verify poll interval
 const PASTE_VERIFY_MS = parseInt(process.env.OCP_TUI_PASTE_VERIFY_MS || "5000", 10); // max wait for pasted prompt to render

@@ -326,44 +423,95 @@ export function buildTuiCmd(claudeBin, model, sessionId, ehome, entrypointMode)
  } else {
    toolArgs = ["--strict-mcp-config", "--disallowedTools", shq("mcp__*")];
  }
+
+  // Effort: pass --effort EXPLICITLY. Without it, the pane's claude inherits a
+  // HOME-dependent effortLevel — real-home mode inherits the operator's
+  // ~/.claude/settings.json (whatever they set for their own interactive use),
+  // env-token scratch mode inherits claude's built-in default (prepareTuiHome never
+  // writes effortLevel) — so latency silently depends on which HOME mode
+  // resolveTuiHome() picked AND on an unrelated operator setting. Pinning it here
+  // removes both. Measured (docs/plans/2026-07-13-tui-latency): explicit low cuts
+  // direct-spawn TTFT p50 10.35s → 6.17s (−40%) and collapses the spread ~15×;
+  // banner-verified to stay on the subscription pool (`· Claude Max`).
+  // OCP_TUI_EFFORT=inherit restores the pre-flag argv byte-for-byte (no --effort).
+  // An unknown value falls back to the default rather than reaching claude's argv:
+  // a typo'd --effort value must not risk a spawn-time usage error in the pane.
+  const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"]; // claude 2.1.207 --help
+  const effortRaw = (process.env.OCP_TUI_EFFORT || "low").trim().toLowerCase();
+  let effortArgs;
+  if (effortRaw === "inherit") {
+    effortArgs = [];
+  } else if (EFFORT_LEVELS.includes(effortRaw)) {
+    effortArgs = ["--effort", effortRaw];
+  } else {
+    console.error(`[tui] invalid OCP_TUI_EFFORT=${JSON.stringify(process.env.OCP_TUI_EFFORT)}; using "low" (valid: ${EFFORT_LEVELS.join("|")}, or "inherit" to omit the flag)`);
+    effortArgs = ["--effort", "low"];
+  }
+
  return [
    envPrefix,
    shq(claudeBin),
    "--model",          shq(model),
    "--session-id",     sessionId,
    ...toolArgs,
+    ...effortArgs,
  ].join(" ");
 }

-// Full per-request TUI lifecycle:
-//   1. Pre-trust the scratch cwd (no trust dialog will appear).
-//   2. Write prompt to a 0600 temp file (no shell injection from prompt content).
-//   3. Boot an interactive `claude` in a fresh tmux session in the scratch cwd; poll
-//      capture-pane until the `? for shortcuts` input bar appears (readiness-poll
-//      replaces the old blind boot sleep). BOOT_MS is the max wait, not a fixed delay.
-//   4. Paste the prompt via tmux load-buffer + paste-buffer -p (bracketed paste) —
-//      reliable for large multi-line prompts where send-keys -l is not (issue #130).
-//      Poll-verify the prompt landed in the input (placeholder gone / [Pasted text]);
-//      fast-fail with tui_paste_not_landed if it never lands (prevents the 120s
-//      wallclock "stuck typing" hang). Then submit with a SEPARATE Enter key event.
-//   5. Block on the native JSONL transcript (located by session-id) until terminal
-//      marker or wall-clock cap.
-//   6. Always teardown: kill session + rm temp dir (even on throw).
-// Returns { text, entrypoint } from readTuiTranscript (entrypoint is the billing-pool
-// classifier, e.g. "cli", or null if the transcript did not include a turn_duration).
-export async function runTuiTurn({
-  prompt,
-  model,
-  claudeBin,
-  home,
-  realHome,
-  cwd,
-  wallclockMs = 120000,
-  entrypointMode = "cli",
-  tmux = defaultTmux,
+// Is a pane alive AND still sitting at its input bar? Used by the warm pool to decide,
+// at hand-out time, whether a pre-booted pane is still usable (a dead/degraded pane must
+// become a MISS → cold path, never a hung turn). capture-pane exits non-zero when the
+// session no longer exists, so this covers "pane gone" and "pane not ready" in one call.
+export function tuiPaneHealthy(tmux, tmuxName) {
+  const r = tmux(["capture-pane", "-p", "-t", tmuxName]);
+  if (!r || r.status !== 0 || typeof r.stdout !== "string") return false;
+  return tuiInputReady(r.stdout);
+}
+
+// Pool pane names carry a "p" marker after the port-scoped prefix:
+//   turn pane: ocp-tui-<port>-<8hex>      (unchanged)
+//   pool pane: ocp-tui-<port>-p<8hex>
+// Purely for operator legibility (`tmux ls` shows which panes are warm). It is NOT the
+// reaper's exemption mechanism — that is the exact-name spare set (see the POOL/REAPER
+// INVARIANT above), so a pooled-LOOKING orphan is still reaped. Both shapes start with
+// sessionPrefixForPort(port), so both remain reapable as "ours", and neither can match
+// LEGACY_SESSION_NAME_RE.
+export function poolPaneName(port, sessionId) {
+  return sessionPrefixForPort(port) + "p" + sessionId.slice(0, 8);
+}
+
+// Boot ONE interactive `claude` pane and wait for its input bar. Shared by the cold
+// request path (runTuiTurn) and the warm pool (lib/tui/pool.mjs) so a pooled pane is
+// spawned with byte-for-byte the same argv, HOME, cwd and trust preparation as a
+// cold-booted one — the pool must not become a second, drifting spawn path.
+//
+// Each pane gets its OWN fresh randomUUID() --session-id, fixed at boot. That is what
+// keeps a pooled pane single-use-safe: its transcript holds exactly one exchange.
+//
+// requireReady: the cold path tolerates a readiness timeout (it falls through and lets
+// the paste-verify decide — pre-existing behaviour, unchanged). The POOL sets it, because
+// a pane that never reached its input bar is worthless as a warm pane and must not be
+// enlisted: throw, let the pool count a bootFailure, and leave the request path to
+// cold-boot as usual.
+// bootMs: max wait for the input bar. Defaults to BOOT_MS (the REQUEST path's cap, which is
+// deliberately tight — a client is blocked on it). The POOL passes POOL_BOOT_MS instead: a
+// background pre-boot has nobody waiting on it, and capping it at the request-path's 4 s
+// made real refills fail (observed live: a refill booting alongside an in-flight turn took
+// >4 s and was discarded, silently lowering the hit rate). Slow != broken for a pre-boot.
+// `sessionId` / `name` (both optional): the caller may supply the pane's identity instead of
+// letting bootTuiPane mint it. The POOL does, because it must know the tmux session's NAME
+// before this function runs — the session is created synchronously below, well before the
+// readiness wait returns, so a pool that only learned the name on resolve could neither spare
+// the session from the reaper nor kill it on shutdown. Supplying BOTH also keeps the name's
+// hex suffix equal to the session-id's, so `tmux ls` correlates to the transcript file.
+export async function bootTuiPane({
+  model, claudeBin, home, realHome, cwd, port, entrypointMode = "cli",
+  tmux = defaultTmux, sessionId = null, name = null, requireReady = false, bootMs = BOOT_MS,
 }) {
-  const sessionId = randomUUID();
-  const tmuxName  = SESSION_PREFIX + sessionId.slice(0, 8);
+  const sid = sessionId || randomUUID();
+  // Port-scoped session name (F7 fix) — see sessionPrefixForPort / reapStaleTuiSessions
+  // for why this instance's own listen port is the namespace discriminator.
+  const tmuxName  = name || (sessionPrefixForPort(port) + sid.slice(0, 8));
  const ehome     = home || process.env.HOME;       // HOME claude runs under (scratch or real)
  const rhome     = realHome || process.env.HOME;   // real home (OAuth + onboarded config source)

@@ -380,42 +528,97 @@ export async function runTuiTurn({
  if (!existsSync(cwd)) mkdirSync(cwd, { recursive: true });
  prepareTuiHome(rhome, ehome, cwd, { envTokenMode });

-  // Write prompt to a temp file (mode 0600) so the content never touches argv.
-  const tmpDir     = mkdtempSync(`${tmpdir()}/ocp-tui-`);
-  const promptFile = `${tmpDir}/prompt.txt`;
-  writeFileSync(promptFile, prompt, { mode: 0o600 });
-
  // Minimal env for spawnSync (tmux itself). The pane's claude env comes exclusively
  // from the `env` prefix string built inside buildTuiCmd — tmux does NOT forward the
  // spawning process's env to the pane, so the {env} here is intentionally minimal.
  const env = { ...process.env };
  env.HOME = ehome; // tmux needs HOME; all claude-specific vars go via buildTuiCmd prefix

+  // Boot the interactive session inside tmux, rooted at the scratch cwd.
+  // Capture the result: if tmux new-session fails (status !== 0) there is no PTY, no
+  // interactive spawn — abort BEFORE the boot wait rather than paste into a non-existent
+  // session or issue a billing request without a verified interactive context.
+  const spawnResult = tmux(
+    ["new-session", "-d", "-s", tmuxName, "-x", "220", "-y", "50", "-c", cwd,
+     buildTuiCmd(claudeBin, model, sid, ehome, entrypointMode)],
+    { env },
+  );
+  if (!spawnResult || spawnResult.status !== 0) {
+    throw new Error("tui_spawn_failed: tmux session not created");
+  }
+
+  // Wait until claude's input bar is actually ready (not a blind sleep).
+  // bootMs is the MAX readiness wait, not a fixed delay.
+  const ready = await pollUntil(() => tuiInputReady(tuiCapturePane(tmux, tmuxName)),
+    { timeoutMs: bootMs, intervalMs: READY_POLL_MS });
+  if (!ready) {
+    if (requireReady) {
+      try { tmux(["kill-session", "-t", tmuxName]); } catch { /* already gone */ }
+      throw new Error("tui_pane_not_ready: input bar did not appear within " + bootMs + "ms");
+    }
+    // Cold path (pre-existing behaviour): readiness timed out; rely on paste-verify.
+    console.error("[tui] input_not_ready", tmuxName);
+  }
+  return { name: tmuxName, sessionId: sid, model, ehome, bootedAt: Date.now() };
+}
+
+// Full per-request TUI lifecycle:
+//   1. Take a WARM pane from the pool if one is available for this model (opt-in;
+//      OCP_TUI_POOL_SIZE=0 => always null => steps 2-3 below are exactly today's path).
+//      A pooled pane is SINGLE-USE: it already carries its own fresh --session-id, it
+//      serves this one turn, and it is killed in the finally like any other pane.
+//   2. On a MISS: pre-trust the scratch cwd, boot an interactive `claude` in a fresh tmux
+//      session in the scratch cwd, poll capture-pane until the `? for shortcuts` input bar
+//      appears (bootTuiPane). BOOT_MS is the max wait, not a fixed delay.
+//   3. Write prompt to a 0600 temp file (no shell injection from prompt content).
+//   4. Paste the prompt via tmux load-buffer + paste-buffer -p (bracketed paste) —
+//      reliable for large multi-line prompts where send-keys -l is not (issue #130).
+//      Poll-verify the prompt landed in the input (placeholder gone / [Pasted text]);
+//      fast-fail with tui_paste_not_landed if it never lands (prevents the 120s
+//      wallclock "stuck typing" hang). Then submit with a SEPARATE Enter key event.
+//   5. Block on the native JSONL transcript (located by THIS pane's session-id) until
+//      terminal marker or wall-clock cap.
+//   6. Always teardown: kill session + rm temp dir (even on throw), and kick a background
+//      pool refill so the next request finds a warm pane.
+// Returns { text, entrypoint } from readTuiTranscript (entrypoint is the billing-pool
+// classifier, e.g. "cli", or null if the transcript did not include a turn_duration).
+export async function runTuiTurn({
+  prompt,
+  model,
+  claudeBin,
+  home,
+  realHome,
+  cwd,
+  port,
+  wallclockMs = 120000,
+  entrypointMode = "cli",
+  tmux = defaultTmux,
+  pool = null,       // TuiPanePool | null — null (default) === today's cold-boot-only path
+  onPane = null,     // optional observer: ({ warm }) => void, for logging/metrics
+}) {
+  // 1. Warm pane, or cold boot. A MISS is never an error — it is exactly today's path.
+  let pane = pool ? pool.acquire(model) : null;
+  const warm = !!pane;
+  // Kick the refill IMMEDIATELY (not after the turn): the replacement pane then boots
+  // CONCURRENTLY with this turn and is warm by the time the next request arrives. Also
+  // runs on a MISS — acquire() has just retargeted the pool to this model, so the miss
+  // that cold-boots today warms the pool for the next caller. Fire-and-forget; it takes
+  // no TuiSemaphore slot (see pool.refill's SLOT ACCOUNTING note).
+  if (pool) pool.refill();
+  if (onPane) { try { onPane({ warm }); } catch { /* observer must never break a turn */ } }
+  if (!pane) {
+    pane = await bootTuiPane({ model, claudeBin, home, realHome, cwd, port, entrypointMode, tmux });
+  }
+  const tmuxName  = pane.name;
+  const sessionId = pane.sessionId;   // THIS pane's own session-id — one session, one turn
+  const ehome     = pane.ehome || home || process.env.HOME;
+
+  // Write prompt to a temp file (mode 0600) so the content never touches argv.
+  const tmpDir     = mkdtempSync(`${tmpdir()}/ocp-tui-`);
+  const promptFile = `${tmpDir}/prompt.txt`;
+  writeFileSync(promptFile, prompt, { mode: 0o600 });
+
  try {
-    // 1. Boot the interactive session inside tmux, rooted at the scratch cwd.
-    //    Capture the result: if tmux new-session fails (status !== 0) there is no
-    //    PTY, no interactive spawn — abort BEFORE the boot sleep rather than paste
-    //    into a non-existent session or issue a billing request without a verified
-    //    interactive context. The finally teardown is still harmless (kill-session
-    //    is a no-op when the session never existed).
-    const spawnResult = tmux(
-      ["new-session", "-d", "-s", tmuxName, "-x", "220", "-y", "50", "-c", cwd,
-       buildTuiCmd(claudeBin, model, sessionId, ehome, entrypointMode)],
-      { env },
-    );
-    if (!spawnResult || spawnResult.status !== 0) {
-      throw new Error("tui_spawn_failed: tmux session not created");
-    }
-
-    // 2. Wait until claude's input bar is actually ready (was: blind sleep(BOOT_MS)).
-    //    BOOT_MS is now the MAX readiness wait, not a fixed delay.
-    const ready = await pollUntil(() => tuiInputReady(tuiCapturePane(tmux, tmuxName)),
-      { timeoutMs: BOOT_MS, intervalMs: READY_POLL_MS });
-    if (!ready) {
-      // (readiness timed out; relying on paste-verify)
-      console.error("[tui] input_not_ready", tmuxName);
-    }
-
    // 3. Paste the prompt via a tmux PASTE BUFFER with bracketed paste (-p), NOT
    //    `send-keys -l`. send-keys of a large multi-line prompt is unreliable: the
    //    embedded newlines arrive as separate key events (effectively repeated Enter),
@@ -441,11 +644,12 @@ export async function runTuiTurn({
    // Submit (separate Enter key event).
    tmux(["send-keys", "-t", tmuxName, "Enter"]);

-    // 4. Block on the native transcript (resolved by session-id) until terminal.
+    // 5. Block on the native transcript (resolved by THIS pane's session-id) until terminal.
    //    Returns { text, entrypoint } from readTuiTranscript.
    return await readTuiTranscript({ home: ehome, sessionId, wallclockMs });
  } finally {
-    // 5. Teardown — always, even on throw.
+    // 6. Teardown — always, even on throw. A pooled pane is torn down here exactly like a
+    //    cold-booted one: SINGLE-USE, never returned to the pool (see pool.mjs).
    try { tmux(["kill-session", "-t", tmuxName]); } catch { /* already gone */ }
    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* best effort */ }
  }
@@ -73,6 +73,17 @@ export function isTerminalLine(obj) {
 // transcript holding one logical exchange). If a future warm-pool ever reuses a
 // session WITHOUT a fresh session-id / clear, earlier-turn text could leak — that
 // author must add user-line scoping here. See spec §7.2.
+//
+// STATUS (warm pool, lib/tui/pool.mjs — the "future warm-pool" this note anticipated):
+// the pool does NOT reuse sessions, so the precondition above still holds and no
+// user-line scoping was added. Each pooled pane is booted with its OWN fresh
+// randomUUID() --session-id (bootTuiPane) and is SINGLE-USE: it serves exactly one turn
+// and is then killed and replaced. One session still means one logical exchange, so the
+// last assistant entry is still that request's answer.
+// The warning therefore stands UNCHANGED for anyone who later wants a pane to serve a
+// SECOND turn (or to reset one with /clear and reuse it): that is a leak, and it needs
+// user-line scoping HERE before it can be safe. Do not relax pool.mjs's single-use rule
+// without doing that work first.
 export function extractLatestAssistantText(events) {
  let text = "";
  for (const ev of events) {
@@ -1,6 +1,6 @@
 {
  "name": "open-claude-proxy",
-  "version": "3.21.0",
+  "version": "3.21.1",
  "description": "OCP (Open Claude Proxy) — use your Claude Pro/Max subscription as an OpenAI-compatible API for any IDE. Works with Cline, OpenCode, Aider, Continue.dev, OpenClaw, and more.",
  "type": "module",
  "bin": {
@@ -22,6 +22,8 @@
 *   CLAUDE_MAX_CONCURRENT        — max concurrent claude processes, -p/stream-json path (default: 8)
 *   CLAUDE_MAX_QUEUE             — max requests waiting for a -p slot before HTTP 429 (default: 16)
 *   OCP_TUI_MAX_CONCURRENT       — max concurrent interactive TUI turns, TUI-mode path (default: 2)
+ *   OCP_TUI_POOL_SIZE            — pre-booted warm `claude` panes held for TUI-mode (default: 0 = off;
+ *                                  max 4). Each is a live idle process; cuts ~3-4s per request.
 *   OCP_SPAWN_REAL_HOME          — "1" forces the -p spawn to use the real HOME (disables the
 *                                  latency spawn-home isolation; default: isolated when a token exists)
 *   CLAUDE_BREAKER_THRESHOLD     — failures in window before circuit opens (default: 6)
@@ -32,7 +34,7 @@
 *   CLAUDE_HEARTBEAT_INTERVAL    — SSE heartbeat interval in ms on streaming path (default: 0 = disabled)
 */
 import { createServer } from "node:http";
-import { spawn, execFileSync } from "node:child_process";
+import { spawn, execFileSync, spawnSync } from "node:child_process";
 import { randomUUID, timingSafeEqual } from "node:crypto";
 import { readFileSync, readdirSync, accessSync, existsSync, constants, chmodSync, statSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -41,9 +43,11 @@ import { homedir } from "node:os";
 import { validateKey, recordUsage, getUsageByKey, getUsageTimeline, getRecentUsage, createKey, listKeys, revokeKey, closeDb, checkQuota, updateKeyQuota, getKeyQuota, findKey, cacheHash, getCachedResponse, setCachedResponse, clearCache, getCacheStats, hasCacheControl, singleflight, getInflightStats } from "./keys.mjs";
 import { DEFAULT_PORT } from "./lib/constants.mjs";
 import { isLoopbackBind } from "./lib/net.mjs";
-import { runTuiTurn, reapStaleTuiSessions, resolveTuiHome } from "./lib/tui/session.mjs";
+import { runTuiTurn, reapStaleTuiSessions, resolveTuiHome, bootTuiPane, tuiPaneHealthy, poolPaneName, POOL_BOOT_MS } from "./lib/tui/session.mjs";
 import { detectTuiUpstreamError } from "./lib/tui/transcript.mjs";
-import { TuiSemaphore, recordTuiEntrypoint, buildTuiHealthBlock } from "./lib/tui/semaphore.mjs";
+import { TuiSemaphore, SemaphoreAbortError, recordTuiEntrypoint, buildTuiHealthBlock } from "./lib/tui/semaphore.mjs";
+import { TuiPanePool, resolvePoolSize, POOL_MAX_SIZE } from "./lib/tui/pool.mjs";
+import { createSerialMutex, createTtlCache, isTokenExpiring, orderLabelsLastGoodFirst } from "./lib/spawn-auth.mjs";

 const __dirname = dirname(fileURLToPath(import.meta.url));
 const _pkg = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf8"));
@@ -350,6 +354,48 @@ const tuiStats = {
  entrypointMismatches: 0,   // count of cli-expected-but-got-other turns
 };

+// ── Warm pane pool (docs/plans/2026-07-13-tui-latency #3) — opt-in; default OFF ─────────
+// OCP_TUI_POOL_SIZE=0 (default) => tuiPool is null => runTuiTurn's cold-boot path is
+// byte-for-byte unchanged. Set it to N (clamped to POOL_MAX_SIZE) to keep N pre-booted
+// `claude` panes warm, each SINGLE-USE (see lib/tui/pool.mjs for why single-use is the
+// load-bearing rule, and lib/tui/session.mjs for the POOL/REAPER INVARIANT).
+//
+// Default-off is deliberate on a stable production path: a warm pane is a LIVE idle
+// `claude` process held whether or not a request ever arrives, so the operator must opt
+// in to that standing cost. Measured saving when on (this host, Sonnet 4.6, --effort low):
+// end-to-end p50 10.17 s (n=6, pool off) -> 6.00 s (n=12 warm hits), i.e. -41%.
+// cli.js does NOT perform this operation (Class B, OCP-owned TUI spawn) — see ADR 0007.
+const TUI_POOL_SIZE = TUI_MODE ? resolvePoolSize(process.env.OCP_TUI_POOL_SIZE) : 0;
+const tuiPool = TUI_POOL_SIZE > 0
+  ? new TuiPanePool({
+      size: TUI_POOL_SIZE,
+      // The POOL mints the pane's identity, not bootTuiPane: the tmux session exists the
+      // instant the boot starts, so the pool must be able to name (hence spare, hence kill)
+      // it before then. Name is derived from the session-id, so `tmux ls` correlates to the
+      // transcript file <HOME>/.claude/projects/*/<sessionId>.jsonl.
+      mintPane: () => {
+        const sessionId = randomUUID();
+        return { sessionId, name: poolPaneName(PORT, sessionId) };
+      },
+      bootPane: (model, ident) => bootTuiPane({
+        model,
+        claudeBin: CLAUDE,
+        home: TUI_HOME,
+        realHome: process.env.HOME,
+        cwd: TUI_CWD,
+        port: PORT,
+        entrypointMode: TUI_ENTRYPOINT,
+        sessionId: ident.sessionId,
+        name: ident.name,
+        requireReady: true,     // a pane that never reached its input bar must not be enlisted
+        bootMs: POOL_BOOT_MS,   // background pre-boot — no client is blocked, so be patient
+      }),
+      killPane: (name) => { try { spawnSync(process.env.OCP_TUI_TMUX_BIN || "tmux", ["kill-session", "-t", name]); } catch { /* already gone */ } },
+      paneHealthy: (name) => tuiPaneHealthy((args) => spawnSync(process.env.OCP_TUI_TMUX_BIN || "tmux", args, { encoding: "utf8" }), name),
+      log: (level, event, data) => logEvent(level, event, data),
+    })
+  : null;
+
 // ── FIX ③ (latency): default-path (-p / stream-json) spawn-home isolation ──────────────
 // PROBLEM (measured, not theoretical): OCP's default spawn inherits the operator's real HOME
 // (loading the global ~/.claude — plugins, skills, hooks) and runs with cwd=~/ocp (loading the
@@ -387,29 +433,104 @@ function prepareSpawnHome(dir = SPAWN_HOME_DIR) {
  } catch { /* best effort — spawn will surface a hard error if the dir is truly unusable */ }
 }

-// Resolve the default-spawn HOME-isolation decision ONCE, lazily + memoized (so it runs after
-// getOAuthCredentials is defined regardless of source order, and the token probe happens at most
-// once). Returns { isolated, home, token } where:
+// Resolve the default-spawn HOME-isolation decision. Returns { isolated, home, reason }:
 //   - isolated:true  → spawn under SPAWN_HOME_DIR with cwd=SPAWN_HOME_DIR + the env token.
 //   - isolated:false → legacy real-HOME spawn, no cwd override (no token, or kill-switch on).
-// NEVER logs/returns the token verbatim to any caller that logs; spawnClaudeProcess uses it only
-// to populate the spawn env. token is null when isolation is off.
-let _spawnHomeMode = null;
+//
+// FIX F6 (2026-07-07): this decision is NO LONGER memoized permanently. The previous version
+// cached it forever at first call, which meant: (a) credentials appearing after startup never
+// enabled isolation; (b) `rm -rf ~/.ocp/spawn-home` at runtime made every isolated spawn ENOENT
+// until restart; (c) during a token-expiry stint /health reported isolated:true while spawns
+// actually ran real-HOME. Re-evaluating per spawn is cheap because F5's 30s keychain TTL cache
+// backs getOAuthCredentials(). This function is the CONFIG-level decision (isolated iff a token
+// resolves AND the kill-switch is off) and has NO fs side effects — the per-spawn EFFECTIVE
+// decision additionally applies the expiry gate (resolveSpawnDecision), and scratch-HOME dir prep
+// moved to ensureSpawnHome() at the isolated spawn site.
+//
+// The token itself is re-resolved FRESH per spawn via resolveSpawnToken(); a memoized token goes
+// stale when its source rotates (the macOS keychain access token rotates ~hourly, refreshed by the
+// operator's real claude), which 401'd every isolated spawn for ~31h on 2026-06-26 (#146). OCP
+// deliberately does NOT refresh the token itself — a refresh-token grant would consume the
+// single-use refresh token and log out the operator's real claude (issue #112).
 function getSpawnHomeMode() {
-  if (_spawnHomeMode) return _spawnHomeMode;
  if (SPAWN_REAL_HOME) {
-    _spawnHomeMode = { isolated: false, home: null, token: null, reason: "kill-switch (OCP_SPAWN_REAL_HOME=1)" };
-    return _spawnHomeMode;
+    return { isolated: false, home: null, reason: "kill-switch (OCP_SPAWN_REAL_HOME=1)" };
  }
-  let token = null;
-  try { token = getOAuthCredentials()?.accessToken || null; } catch { token = null; }
+  let hasToken = false;
+  try { hasToken = !!(getOAuthCredentials()?.accessToken); } catch { hasToken = false; }
+  if (hasToken) return { isolated: true, home: SPAWN_HOME_DIR, reason: "oauth token resolved" };
+  return { isolated: false, home: null, reason: "no oauth token resolvable" };
+}
+
+// FIX F6: re-verify the scratch HOME exists before each isolated spawn and re-create it if it was
+// deleted at runtime (it used to be prepared once at startup, so a runtime deletion made every
+// isolated spawn fail ENOENT until restart). mkdirSync is recursive+idempotent → cheap to re-run.
+function ensureSpawnHome(dir = SPAWN_HOME_DIR) {
+  if (!existsSync(`${dir}/.claude`)) prepareSpawnHome(dir);
+}
+
+// Resolve a FRESH OAuth access token for an isolated spawn. Read-only (keychain / credentials.json
+// / env) — NEVER refreshes/rotates (see getSpawnHomeMode note). Returns null if none resolvable OR
+// if a known expiry is within the 5-min buffer (isTokenExpiring): a null return makes the caller
+// fall back to real HOME, where the spawned claude refreshes the credential natively and self-heals
+// (the keychain token is then fresh again → next spawn is fast). The env-token path (Linux) carries
+// no expiresAt → never expiry-gated (those tokens are long-lived).
+function resolveSpawnToken() {
+  try {
+    const creds = getOAuthCredentials();
+    if (!creds?.accessToken) return null;
+    if (isTokenExpiring(creds)) return null; // 5-min buffer; applied to the CACHED creds every use
+    return creds.accessToken;
+  } catch { return null; }
+}
+
+// FIX F3 (2026-07-07): serializes ONLY the real-HOME fallback spawns. Isolated spawns (the common
+// fast path) never touch this mutex.
+const realHomeFallbackMutex = createSerialMutex();
+
+// Resolve the EFFECTIVE per-spawn HOME/token decision. Returns
+//   { isolated, home, token, releaseFallback }
+// `releaseFallback` is non-null ONLY for a real-HOME fallback holder — the caller MUST call it on
+// spawn teardown (wired into cleanup()); it releases the serialization mutex. It is null (no-op)
+// for isolated and stable real-HOME (kill-switch / no-token) spawns.
+//
+// This is async so the real-HOME fallback can `await` the mutex; the keychain reads inside stay
+// synchronous (F5 keeps the call sites off async conversion).
+async function resolveSpawnDecision() {
+  const shm = getSpawnHomeMode();
+  if (!shm.isolated) return { isolated: false, home: null, token: null, releaseFallback: null };
+  const token = resolveSpawnToken();
  if (token) {
-    prepareSpawnHome(SPAWN_HOME_DIR);
-    _spawnHomeMode = { isolated: true, home: SPAWN_HOME_DIR, token, reason: "oauth token resolved" };
-  } else {
-    _spawnHomeMode = { isolated: false, home: null, token: null, reason: "no oauth token resolvable" };
+    ensureSpawnHome(shm.home);
+    return { isolated: true, home: shm.home, token, releaseFallback: null };
  }
-  return _spawnHomeMode;
+  // Token is present but within the 5-min expiry window → we would fall back to real HOME, where
+  // the spawned claude refreshes the credential natively. HAZARD PREVENTED: without serialization,
+  // every concurrent -p spawn inside this window runs claude under the real HOME simultaneously,
+  // and each spawned claude races a `refresh_token` grant against the SAME single-use refresh
+  // token — rotating it out from under the others AND the operator's own real claude (the
+  // credential-fork hazard; #112 / #146 class). Serialize: admit ONE real-HOME spawn at a time.
+  // When the next waiter is admitted (the prior holder torn down → its claude has had its lifetime
+  // to refresh the keychain), re-run resolveSpawnToken(): a now-fresh token means we proceed
+  // ISOLATED and release the mutex immediately, so the queue drains to the fast path instead of
+  // piling every request into the real HOME.
+  const release = await realHomeFallbackMutex.acquire();
+  try {
+    // Drop the 30s keychain TTL cache so the re-check reads FRESH keychain state — otherwise a
+    // waiter admitted right after the prior holder's claude refreshed the token could still see the
+    // stale (expiring) cached creds and needlessly fall back to real HOME again for up to ~30s.
+    invalidateKeychainReadCache();
+    const retry = resolveSpawnToken();
+    if (retry) {
+      release();
+      ensureSpawnHome(shm.home);
+      return { isolated: true, home: shm.home, token: retry, releaseFallback: null };
+    }
+  } catch (e) {
+    release();
+    throw e;
+  }
+  return { isolated: false, home: null, token: null, releaseFallback: release };
 }

 // ── FIX ⑥ (concurrency): bounded wait-queue for the -p / stream-json path ──────────────
@@ -431,16 +552,61 @@ class ConcurrencyOverflowError extends Error {
  constructor(message) { super(message); this.name = "ConcurrencyOverflowError"; this.httpStatus = 429; this.retryAfter = CLAUDE_QUEUE_RETRY_AFTER; }
 }

+// Tagged error for audit finding F2: the client disconnected while queued (or was already gone
+// before we even tried to queue it). Distinct from ConcurrencyOverflowError so callers never send
+// a response on this path — there is no socket left to write to.
+class RequestDisconnectedError extends Error {
+  constructor(message) { super(message); this.name = "RequestDisconnectedError"; }
+}
+
+// Build an AbortSignal that fires when `res` (an http.ServerResponse) closes — i.e. the client
+// disconnected. Used to cancel a QUEUED concurrency-slot wait (F2) so a client that gives up
+// before a slot is granted is spliced out of the wait queue instead of eventually spawning a
+// claude process for a dead socket. If `res` has already closed by the time we get here (its
+// underlying stream already torn down), the signal is returned pre-aborted so acquire() rejects
+// immediately without ever touching the queue — the "close already fired before we attach" case.
+// `detach()` MUST be called once the wait settles (granted or rejected) to avoid a listener leak.
+function closeSignalFor(res) {
+  const controller = new AbortController();
+  if (!res || typeof res.on !== "function") return { signal: controller.signal, detach() {} };
+  if (res.destroyed) {
+    controller.abort();
+    return { signal: controller.signal, detach() {} };
+  }
+  const onClose = () => controller.abort();
+  res.on("close", onClose);
+  return { signal: controller.signal, detach() { res.removeListener("close", onClose); } };
+}
+
 // Acquire a -p concurrency slot, queuing if all are busy (up to CLAUDE_MAX_QUEUE). Resolves to a
 // release() fn that MUST be called exactly once on every exit path (wired into ctx.cleanup()).
-// Rejects with ConcurrencyOverflowError when the wait-queue is full. Increments stats.queued while
-// waiting (decremented on acquire) and stats.queueRejections on overflow.
-async function acquireClaudeSlot() {
-  stats.queued = claudeSemaphore.queued + 1; // reflect this waiter before we (maybe) block
+// Rejects with ConcurrencyOverflowError when the wait-queue is full, or with
+// RequestDisconnectedError when `res` closes before a slot is granted (F2) — the caller must not
+// spawn claude in that case. `res` is optional (back-compat for any caller without a live response
+// object); omitting it just means a queued wait can't be cancelled early.
+//
+// F8 fix: stats.queued is set from claudeSemaphore.queued AFTER calling acquire() (not before) —
+// acquire() synchronously updates _inflight/_waiters before its Promise ever resolves, so reading
+// .queued right after the call already reflects reality. The old code set `queued + 1` BEFORE
+// calling acquire() to account for "this waiter", which over-reported by 1 whenever the slot was
+// granted immediately (the common case, not a queue at all).
+async function acquireClaudeSlot(res) {
+  const { signal, detach } = closeSignalFor(res);
+  const slot = claudeSemaphore.acquire(signal);
+  stats.queued = claudeSemaphore.queued; // accurate: acquire() already updated the queue synchronously
  try {
-    await claudeSemaphore.acquire();
+    await slot;
  } catch (e) {
+    detach();
    stats.queued = claudeSemaphore.queued;
+    if (e instanceof SemaphoreAbortError) {
+      // Client-driven cancellation, not backpressure — do NOT count it as a queueRejection or
+      // log it as concurrency_queue_full (that log/counter means "the queue itself is full").
+      logEvent("info", "concurrency_wait_cancelled", {
+        reason: "client_disconnected", inflight: claudeSemaphore.inflight, queued: claudeSemaphore.queued,
+      });
+      throw new RequestDisconnectedError("client disconnected while waiting for a concurrency slot");
+    }
    stats.queueRejections++;
    logEvent("warn", "concurrency_queue_full", {
      limit: claudeSemaphore.limit, maxQueue: claudeSemaphore.maxQueue,
@@ -450,6 +616,7 @@ async function acquireClaudeSlot() {
      `backpressure: concurrency limit (${claudeSemaphore.limit}) reached and wait queue ` +
      `(${claudeSemaphore.maxQueue}) is full — retry shortly`);
  }
+  detach();
  stats.queued = claudeSemaphore.queued;
  let released = false;
  return function releaseClaudeSlot() {
@@ -648,13 +815,45 @@ const cacheCleanupInterval = setInterval(() => {
 // mechanism and the 15-min cadence makes the window negligible).
 // Gated on TUI_MODE — zero effect (no kill-server, no list-sessions) when TUI is off.
 // cli.js does NOT perform this operation (Class B, OCP-owned TUI spawn) — see ADR 0007.
+//
+// WARM POOL INTERACTION (the crux — see the POOL/REAPER INVARIANT in lib/tui/session.mjs).
+// A warm pooled pane is one of OUR OWN ocp-tui-<port>-* sessions that is alive and idle BY
+// DESIGN, and this sweep fires precisely when the instance is idle — i.e. exactly when the
+// pool is full. Two things are therefore required, and both are done here:
+//   (a) DRAIN the pool BEFORE the sweep. Zombie reaping is possible ONLY via kill-server,
+//       and a live pooled pane suppresses kill-server (it is a live child of the tmux
+//       server). A permanently-full pool would otherwise permanently disable the very
+//       thing this tick exists to do. Draining costs one pane re-boot per tick (~1.2 s of
+//       background work every 15 min) and is invisible to callers: a request landing in the
+//       drain→refill gap simply MISSES the pool and takes today's cold path.
+//   (b) Pass the pool's live registry as `spare` anyway. After (a) it is empty, so this is
+//       belt-and-braces — it makes it impossible for THIS call site (or a future one) to
+//       kill a live pooled pane even if the drain were ever removed or reordered.
+// RESIDUAL (unchanged in kind from the pre-pool code, and explicitly accepted there): a
+// request arriving in the narrow window between the idle-check and kill-server has its pane
+// torn down and fails cleanly via runTuiTurn's honesty gates. The drain widens that window
+// by the cost of N kill-session calls (single-digit ms), not materially.
 const TUI_REAP_INTERVAL_MS = 15 * 60 * 1000;
 const tuiReapInterval = TUI_MODE ? setInterval(() => {
  if (tuiSemaphore.inflight > 0 || tuiSemaphore.queued > 0) return; // a turn is live — defer
  try {
-    const n = reapStaleTuiSessions();
-    if (n) logEvent("info", "tui_reaped_stale_sessions", { count: n, trigger: "periodic" });
+    const drained = tuiPool ? tuiPool.drain() : 0;
+    // F7 fix: scope to THIS instance's own port; a sibling ocp-tui-<otherPort>-* session
+    // (a second OCP instance on the same host) is treated as foreign, same as olp-tui-*.
+    // includeLegacy is NOT set here — see reapStaleTuiSessions' comment: the periodic sweep
+    // conservatively treats any lingering bare-prefix legacy session as foreign so it can
+    // never trigger kill-server on a steady-state tick; only the one-time boot reap below
+    // claims legacy-shaped zombies.
+    const n = reapStaleTuiSessions({ port: PORT, spare: tuiPool ? tuiPool.liveNames() : null });
+    if (n || drained) {
+      logEvent("info", "tui_reaped_stale_sessions", { count: n, poolDrained: drained, trigger: "periodic" });
+    }
  } catch (e) { logEvent("error", "tui_periodic_reap_failed", { error: e.message }); }
+  finally {
+    // Refill in the background regardless of how the sweep went — a throw mid-sweep must not
+    // leave the pool permanently paused (it would silently degrade to the cold path forever).
+    if (tuiPool) { try { tuiPool.resume(); } catch { /* best effort */ } }
+  }
 }, TUI_REAP_INTERVAL_MS) : null;
 if (tuiReapInterval && typeof tuiReapInterval.unref === "function") tuiReapInterval.unref();

@@ -906,7 +1105,7 @@ function getModelTier(cliModel) {
 // budget. releaseSlot is wired into the idempotent cleanup() so the slot is freed on EVERY exit
 // path (close/error/timeout/abort). Back-compat: releaseSlot defaults to a no-op so any future
 // internal caller that does its own gating still works.
-function spawnClaudeProcess(model, messages, conversationId, keyName, releaseSlot = () => {}) {
+function spawnClaudeProcess(model, messages, conversationId, keyName, releaseSlot = () => {}, spawnDecision = null) {
  const cliModel = MODEL_MAP[model] || model;

  // Circuit breaker: disabled (see comment at top of breaker section)
@@ -943,22 +1142,24 @@ function spawnClaudeProcess(model, messages, conversationId, keyName, releaseSlo
    env.CLAUDE_CODE_DISABLE_AUTO_MEMORY = "1";
  }

-  // FIX ③ (latency): default-path spawn-home isolation. When a token is resolvable (and the
-  // OCP_SPAWN_REAL_HOME kill-switch is off), run claude under a credential-free minimal HOME
-  // with cwd = that same neutral dir, so it loads NONE of the operator's global ~/.claude
-  // (plugins/skills/hooks) or the ~/ocp project CLAUDE.md/skills — the measured 10–28s → 3–7s
-  // latency win. The env token is authoritative for `-p` (unlike interactive claude). When no
-  // token is resolvable, falls back to real HOME + inherited cwd (zero regression). See
-  // getSpawnHomeMode() / prepareSpawnHome() above. The DISABLE_CLAUDE_MDS / AUTO_MEMORY flags
-  // are set unconditionally in isolated mode (belt-and-braces; mirrors the TUI path).
-  const spawnHome = getSpawnHomeMode();
+  // FIX ③ (latency) + F3 (concurrency): apply the pre-resolved per-spawn HOME/token decision.
+  // The decision is resolved ASYNC in the caller (resolveSpawnDecision) so the real-HOME fallback
+  // serialization can await its mutex; here we only apply the result. When isolated, run claude
+  // under a credential-free minimal HOME with cwd = that same neutral dir, so it loads NONE of the
+  // operator's global ~/.claude (plugins/skills/hooks) or the ~/ocp project CLAUDE.md/skills — the
+  // measured 10–28s → 3–7s latency win. The env token is authoritative for `-p` (unlike
+  // interactive claude). When no fresh token is resolvable, decision.isolated is false → real HOME
+  // + inherited cwd (zero regression), and the spawned claude resolves+refreshes credentials
+  // natively. The DISABLE_CLAUDE_MDS / AUTO_MEMORY flags are set unconditionally in isolated mode
+  // (belt-and-braces; mirrors the TUI path).
+  const decision = spawnDecision || { isolated: false, releaseFallback: null };
  const spawnOpts = { env, stdio: ["pipe", "pipe", "pipe"] };
-  if (spawnHome.isolated) {
-    env.HOME = spawnHome.home;
-    env.CLAUDE_CODE_OAUTH_TOKEN = spawnHome.token; // env token is authoritative for -p
+  if (decision.isolated && decision.token) {
+    env.HOME = decision.home;
+    env.CLAUDE_CODE_OAUTH_TOKEN = decision.token; // env token is authoritative for -p
    env.CLAUDE_CODE_DISABLE_CLAUDE_MDS = "1";
    env.CLAUDE_CODE_DISABLE_AUTO_MEMORY = "1";
-    spawnOpts.cwd = spawnHome.home; // neutral cwd: no project CLAUDE.md/skills
+    spawnOpts.cwd = decision.home; // neutral cwd: no project CLAUDE.md/skills
  }

  const proc = spawn(CLAUDE, cliArgs, spawnOpts);
@@ -977,6 +1178,11 @@ function spawnClaudeProcess(model, messages, conversationId, keyName, releaseSlo
    // and cleanup() is guarded by `cleaned`, so the slot is released exactly once on the first
    // exit path reached (proc 'exit' fires before 'close'; 'error' covers spawn failure).
    try { releaseSlot(); } catch { /* never let release throw out of cleanup */ }
+    // F3: release the real-HOME fallback serialization mutex (no-op for isolated/normal spawns).
+    // By now this spawn's claude has had its lifetime to refresh the keychain token, so the next
+    // queued fallback waiter re-checks resolveSpawnToken() and proceeds ISOLATED with the now-fresh
+    // token instead of piling into the real HOME. Idempotent; cleanup() is guarded by `cleaned`.
+    try { if (decision.releaseFallback) decision.releaseFallback(); } catch { /* never throw out of cleanup */ }
  }

  // Guarantee slot release on ANY exit path (normal close, error, timeout kill,
@@ -1046,18 +1252,37 @@ function spawnClaudeProcess(model, messages, conversationId, keyName, releaseSlo
 // We accumulate full text across all content_block_delta events plus the
 // assistant-aggregate fallback, then resolve with the assembled string.
 // Reference: OLP ADR 0009 Amendment 1 + commit 97e7d16.
-async function callClaude(model, messages, conversationId, keyName) {
+// `res` (optional, F2) is the client's http.ServerResponse — passed through so a queued wait
+// can be cancelled the moment the client disconnects, instead of spawning claude for a dead
+// socket once a slot finally frees up.
+async function callClaude(model, messages, conversationId, keyName, res) {
  // FIX ⑥: acquire a concurrency slot first (queues up to CLAUDE_MAX_QUEUE; rejects with a
-  // ConcurrencyOverflowError → 429 when the queue is full). The release fn is passed into the
-  // spawn so the idempotent cleanup() frees it on every exit path. If the spawn itself throws
-  // synchronously (before cleanup is wired), release here so the slot never leaks.
-  const releaseSlot = await acquireClaudeSlot();
+  // ConcurrencyOverflowError → 429 when the queue is full, or a RequestDisconnectedError (F2)
+  // if the client goes away first). The release fn is passed into the spawn so the idempotent
+  // cleanup() frees it on every exit path. If the spawn itself throws synchronously (before
+  // cleanup is wired), release here so the slot never leaks.
+  // F2×F3 composition: the slot acquire comes FIRST and is the cancellable step — a client
+  // that disconnects while queued rejects here, BEFORE resolveSpawnDecision() runs, so a
+  // cancelled request can never acquire (or briefly hold) the real-HOME fallback mutex.
+  const releaseSlot = await acquireClaudeSlot(res);
+  // F3: resolve the per-spawn HOME/token decision (may serialize on the real-HOME fallback
+  // mutex). If it throws, release the just-acquired slot before propagating — cleanup() is
+  // not wired yet at this point.
+  let spawnDecision;
+  try {
+    spawnDecision = await resolveSpawnDecision();
+  } catch (err) {
+    releaseSlot();
+    throw err;
+  }
  return new Promise((resolve, reject) => {
    let ctx;
    try {
-      ctx = spawnClaudeProcess(model, messages, conversationId, keyName, releaseSlot);
+      ctx = spawnClaudeProcess(model, messages, conversationId, keyName, releaseSlot, spawnDecision);
    } catch (err) {
      releaseSlot();
+      // Spawn threw before cleanup() was wired → release the fallback mutex here so it never leaks.
+      try { spawnDecision.releaseFallback?.(); } catch { /* best effort */ }
      return reject(err);
    }

@@ -1128,26 +1353,59 @@ async function callClaude(model, messages, conversationId, keyName) {
 // flag that could perturb cc_entrypoint classification.
 // Authority: claude CLI v2.1.158 interactive mode (cc_entrypoint=cli).
 // SECURITY: A-path single-user ONLY — home is NOT isolation (see ADR 0007).
-function callClaudeTui(model, messages, _conversationId, _keyName) {
+// `res` (optional, F2) is the client's http.ServerResponse — see closeSignalFor.
+async function callClaudeTui(model, messages, _conversationId, _keyName, res) {
  const cliModel = MODEL_MAP[model] || model;
  const prompt = messagesToPrompt(messages); // includes system as [System] inline
  recordModelRequest(cliModel, prompt.length);
-  // C-4: gate the heavy interactive boot behind the TUI semaphore. run() acquires a slot
-  // (queuing if all are busy, up to maxQueue), then releases in a finally so any throw from
-  // runTuiTurn (tmux spawn failure, paste-not-landed) OR from the honesty gates below
-  // (truncation / error banner) can NEVER leak a slot. tuiSemaphore.inflight feeds /health.
-  return tuiSemaphore.run(() => runTuiTurn({
-    prompt,
-    model: cliModel,
-    claudeBin: CLAUDE,
-    home: TUI_HOME,
-    realHome: process.env.HOME,
-    cwd: TUI_CWD,
-    wallclockMs: TUI_WALLCLOCK_MS,
-    entrypointMode: TUI_ENTRYPOINT,
-  }).then(({ text, entrypoint, truncated }) => {
+  // C-4: gate the heavy interactive boot behind the TUI semaphore (queuing if all slots are
+  // busy, up to maxQueue). F2: `signal` (tied to `res` "close") cancels a QUEUED wait the
+  // instant the client disconnects, so a dead socket never triggers a cold-boot tmux+claude
+  // spawn; detach() drops the "close" listener as soon as the wait settles rather than
+  // holding it for the whole (up to 120s) turn.
+  const { signal, detach } = closeSignalFor(res);
+  try {
+    await tuiSemaphore.acquire(signal);
+  } catch (err) {
+    detach();
+    if (err instanceof SemaphoreAbortError) {
+      // L1: client-driven cancellation, not an upstream failure — info, not error (mirrors
+      // acquireClaudeSlot's concurrency_wait_cancelled on the -p path).
+      logEvent("info", "concurrency_wait_cancelled", {
+        reason: "client_disconnected", path: "tui", inflight: tuiSemaphore.inflight, queued: tuiSemaphore.queued,
+      });
+      throw new RequestDisconnectedError("client disconnected while waiting for a TUI concurrency slot");
+    }
+    throw err;
+  }
+  detach();
+  // release() runs in a finally so any throw from runTuiTurn (tmux spawn failure,
+  // paste-not-landed) OR from the honesty gates below (truncation / error banner) can NEVER
+  // leak a slot. tuiSemaphore.inflight feeds /health.
+  try {
+    const { text, entrypoint, truncated } = await runTuiTurn({
+      prompt,
+      model: cliModel,
+      claudeBin: CLAUDE,
+      home: TUI_HOME,
+      realHome: process.env.HOME,
+      cwd: TUI_CWD,
+      port: PORT, // F7 fix: port-scopes the tmux session name so a sibling OCP instance on a
+                  // different port never collides with this instance's reap/kill-server logic.
+      wallclockMs: TUI_WALLCLOCK_MS,
+      entrypointMode: TUI_ENTRYPOINT,
+      // Warm pane pool (null unless OCP_TUI_POOL_SIZE > 0 → today's cold path exactly).
+      // A pooled pane is single-use: runTuiTurn kills it in its finally like any other.
+      pool: tuiPool,
+      // Only observe when the pool is ON — with it off (the default) no new log line is
+      // emitted, so the disabled path stays byte-for-byte today's, logs included.
+      onPane: tuiPool
+        ? ({ warm }) => logEvent("info", warm ? "tui_pool_hit" : "tui_pool_miss",
+            { model: cliModel, warmRemaining: tuiPool.warm })
+        : null,
+    });
    // ── Honesty gates (issue #133) ─ run BEFORE recordModelSuccess / cache write-back.
-    // A throw here propagates to the .catch below (recordModelError + reject), so the
+    // A throw here propagates to the catch below (recordModelError + reject), so the
    // result never reaches the downstream setCachedResponse / singleflight / SUCCESS path.

    // C-2: the wall-clock cap hit with partial text and NO terminal marker — the turn
@@ -1182,10 +1440,12 @@ function callClaudeTui(model, messages, _conversationId, _keyName) {
      logEvent("warn", "tui_entrypoint_mismatch", { expected: "cli", got: entrypoint, model: cliModel });
    }
    return text;
-  }).catch((err) => {
+  } catch (err) {
    recordModelError(cliModel, false);
    throw err;
-  }));
+  } finally {
+    tuiSemaphore.release();
+  }
 }

 // ── SSE heartbeat (opt-in idle watchdog) ────────────────────────────────
@@ -1231,23 +1491,39 @@ async function callClaudeStreaming(model, messages, conversationId, res, authInf
  // FIX ⑥: acquire a concurrency slot first (queues up to CLAUDE_MAX_QUEUE). On overflow, surface
  // HTTP 429 + Retry-After (NOT 500). Release is wired into cleanup() for every exit path; if the
  // spawn throws synchronously before cleanup is wired, release here.
+  // F2: pass `res` so a queued wait is cancelled the instant this client disconnects — the client
+  // is already gone in that case, so there is no response to send back.
  let releaseSlot;
  try {
-    releaseSlot = await acquireClaudeSlot();
+    releaseSlot = await acquireClaudeSlot(res);
  } catch (err) {
+    if (err instanceof RequestDisconnectedError) return; // client gone — nothing to write to
    if (err instanceof ConcurrencyOverflowError) {
      return jsonResponse(res, 429, { error: { message: sanitizeError(err.message), type: "rate_limit_error" } }, { "Retry-After": String(err.retryAfter) });
    }
    return jsonResponse(res, 500, { error: { message: sanitizeError(err.message), type: "proxy_error" } });
  }

-  let ctx;
+  // F3: resolve the per-spawn HOME/token decision (may serialize on the real-HOME fallback
+  // mutex). F2×F3 composition: this runs strictly AFTER the (cancellable) slot acquire, so a
+  // request cancelled while queued never touches the fallback mutex. If it throws, release
+  // the just-acquired slot before responding — cleanup() is not wired yet at this point.
+  let spawnDecision;
  try {
-    ctx = spawnClaudeProcess(model, messages, conversationId, authInfo.keyName, releaseSlot);
+    spawnDecision = await resolveSpawnDecision();
  } catch (err) {
    releaseSlot();
    return jsonResponse(res, 500, { error: { message: sanitizeError(err.message), type: "proxy_error" } });
  }
+  let ctx;
+  try {
+    ctx = spawnClaudeProcess(model, messages, conversationId, authInfo.keyName, releaseSlot, spawnDecision);
+  } catch (err) {
+    releaseSlot();
+    // Spawn threw before cleanup() was wired → release the fallback mutex here so it never leaks.
+    try { spawnDecision.releaseFallback?.(); } catch { /* best effort */ }
+    return jsonResponse(res, 500, { error: { message: sanitizeError(err.message), type: "proxy_error" } });
+  }

  const { proc, cliModel, conversationId: convId, t0, cleanup, clearOverallTimer, handleSessionFailure, markFirstByte } = ctx;
  let stderr = "";
@@ -1517,6 +1793,51 @@ const OAUTH_REFRESH_MIN_BACKOFF = 60 * 1000;
 const OAUTH_REFRESH_MAX_BACKOFF = 3600 * 1000;
 let oauthRefreshBackoff = { nextAttemptAt: 0, currentDelay: OAUTH_REFRESH_MIN_BACKOFF };

+// FIX F5 (2026-07-07): the macOS keychain read (`security find-generic-password`, up to 5s × 2
+// labels when the first label misses) ran on EVERY -p spawn's hot path, blocking the event loop
+// (worst case 10s) and stalling all in-flight SSE streams. Two minimal, sync-preserving mitigations:
+//   (a) memoize the last-good keychain label and try it FIRST → one exec instead of two on the
+//       steady-state path (orderLabelsLastGoodFirst);
+//   (b) a short (30s) TTL cache of the keychain read result (createTtlCache).
+// SAFETY vs the #146 regression: #146 was a token memoized FOREVER at startup that went stale and
+// 401'd. This is a 30s TTL (not forever), AND resolveSpawnToken() re-applies the 5-min expiry gate
+// (isTokenExpiring) to the CACHED creds on EVERY use — the creds object carries `expiresAt`, so a
+// token expiring within the cache window is still rejected → real-HOME fallback. A short TTL bounds
+// how often we re-READ the keychain; it does NOT bound how often we re-DECIDE expiry. This is why a
+// short-TTL keychain cache + a per-use expiry check does not reintroduce the forever-stale bug.
+const KEYCHAIN_LABELS = ["claude-code-credentials", "Claude Code-credentials"];
+const KEYCHAIN_CACHE_TTL_MS = 30 * 1000;
+const _keychainCache = createTtlCache({ ttlMs: KEYCHAIN_CACHE_TTL_MS });
+let _lastGoodKeychainLabel = null;
+
+// Read the macOS keychain credentials, label-memoized + short-TTL cached (F5). Sync (execFileSync);
+// returns the `claudeAiOauth` creds object or null.
+function readKeychainCreds() {
+  return _keychainCache.get(() => {
+    for (const label of orderLabelsLastGoodFirst(KEYCHAIN_LABELS, _lastGoodKeychainLabel)) {
+      try {
+        const raw = execFileSync("security", [
+          "find-generic-password", "-s", label, "-w"
+        ], { encoding: "utf8", timeout: 5000 }).trim();
+        const creds = JSON.parse(raw);
+        if (creds?.claudeAiOauth?.accessToken) {
+          _lastGoodKeychainLabel = label; // remember the winner → try it first next time
+          return creds.claudeAiOauth;
+        }
+      } catch { /* try next label */ }
+    }
+    return null;
+  });
+}
+
+// F3 drain helper: drop the F5 keychain TTL cache so the NEXT getOAuthCredentials() re-reads the
+// keychain from scratch. Called under the real-HOME fallback mutex just before the re-check, so a
+// waiter admitted after the prior holder's claude refreshed the keychain sees the FRESH token
+// immediately (and proceeds ISOLATED) instead of waiting out the ≤30s TTL on the stale creds.
+function invalidateKeychainReadCache() {
+  _keychainCache.clear();
+}
+
 function getOAuthCredentials() {
  // 1. Env var fallback — highest precedence for explicit overrides.
  if (process.env.CLAUDE_CODE_OAUTH_TOKEN) {
@@ -1530,17 +1851,8 @@ function getOAuthCredentials() {
    if (creds?.claudeAiOauth?.accessToken) return creds.claudeAiOauth;
  } catch { /* fall through to macOS keychain */ }

-  // 3. macOS keychain (both label formats)
-  for (const label of ["claude-code-credentials", "Claude Code-credentials"]) {
-    try {
-      const raw = execFileSync("security", [
-        "find-generic-password", "-s", label, "-w"
-      ], { encoding: "utf8", timeout: 5000 }).trim();
-      const creds = JSON.parse(raw);
-      if (creds?.claudeAiOauth?.accessToken) return creds.claudeAiOauth;
-    } catch { /* try next */ }
-  }
-  return null;
+  // 3. macOS keychain (both label formats) — F5: label-memoized + 30s TTL cached (see above).
+  return readKeychainCreds();
 }

 async function refreshOAuthToken(refreshToken) {
@@ -1874,9 +2186,12 @@ function applySettingUpdate(key, value) {

  switch (key) {
    case "timeout":          TIMEOUT = value; break;
-    // FIX ⑥: keep the -p wait-queue semaphore's limit in sync with the runtime MAX_CONCURRENT
-    // so a /settings change to maxConcurrent actually changes how many claude procs run at once.
-    case "maxConcurrent":    MAX_CONCURRENT = value; claudeSemaphore.limit = Math.max(1, value); break;
+    // FIX ⑥ + F1: keep the -p wait-queue semaphore's limit in sync with the runtime MAX_CONCURRENT
+    // so a /settings change to maxConcurrent actually changes how many claude procs run at once —
+    // in BOTH directions. setLimit() (not a bare `.limit =` assignment) is required: lowering
+    // needs release() to stop over-granting until inflight drains under the new cap, and raising
+    // needs queued waiters woken immediately to use the new headroom. See lib/tui/semaphore.mjs.
+    case "maxConcurrent":    MAX_CONCURRENT = value; claudeSemaphore.setLimit(value); break;
    case "sessionTTL":       SESSION_TTL = value; break;
    case "maxPromptChars":   MAX_PROMPT_CHARS = value; break;
    case "cacheTTL":         CACHE_TTL = value; break;
@@ -2033,7 +2348,7 @@ async function handleChatCompletions(req, res) {
      const t0TuiStream = Date.now();
      const promptCharsTuiStream = messages.reduce((a, m) => a + contentToText(m.content).length, 0);
      try {
-        const content = await callClaudeTui(model, messages, conversationId, req._authKeyName);
+        const content = await callClaudeTui(model, messages, conversationId, req._authKeyName, res);
        if (CACHE_TTL > 0 && req._cacheHash) {
          try { setCachedResponse(req._cacheHash, model, content); } catch (e) { logEvent("error", "cache_write_failed", { error: e.message }); }
        }
@@ -2070,15 +2385,27 @@ async function handleChatCompletions(req, res) {
        // will re-read the freshly-populated cache entry here rather than spawning.
        const recheck = getCachedResponse(req._cacheHash, CACHE_TTL);
        if (recheck) return recheck.response;
-        const c = await upstreamCall(model, messages, conversationId, req._authKeyName);
+        const c = await upstreamCall(model, messages, conversationId, req._authKeyName, res);
        try { setCachedResponse(req._cacheHash, model, c); } catch (e) { logEvent("error", "cache_write_failed", { error: e.message }); }
        return c;
-      });
+      },
+      // M1: if the LEADER disconnected while queued (F2), its RequestDisconnectedError is
+      // personal to the leader — a live follower must not inherit it as a spurious 500.
+      // retryIf makes this follower re-enter singleflight with its OWN fn (own res, own
+      // disconnect signal), becoming the new leader or joining a retrying sibling's flight —
+      // but only while OUR client is still connected. If our client is also gone, the
+      // rejection propagates and the RDE early-return in the catch below ends it quietly.
+      (err) => err instanceof RequestDisconnectedError && !res.destroyed);
      const id = `chatcmpl-${randomUUID()}`;
      completionResponse(res, id, model, content);
      try { recordUsage({ keyId: req._authKeyId, keyName: req._authKeyName, model, promptChars, responseChars: content.length, elapsedMs: Date.now() - t0Usage, success: true }); } catch (e) { logEvent("error", "usage_record_failed", { error: e.message }); }
      return;
    } catch (err) {
+      // L1: a client disconnect while queued is NOT an upstream failure — mirror the
+      // streaming path (which returns without recording anything): no usage-failure row,
+      // no [proxy] error log, no error response (the socket is gone). The disconnect is
+      // already logged at info level (concurrency_wait_cancelled) by acquireClaudeSlot.
+      if (err instanceof RequestDisconnectedError) { try { res.end(); } catch {} return; }
      try { recordUsage({ keyId: req._authKeyId, keyName: req._authKeyName, model, promptChars, responseChars: 0, elapsedMs: Date.now() - t0Usage, success: false }); } catch (e) { logEvent("error", "usage_record_failed", { error: e.message }); }
      console.error(`[proxy] error: ${err.message}`);
      if (res.headersSent || res.writableEnded || res.destroyed) {
@@ -2091,11 +2418,14 @@ async function handleChatCompletions(req, res) {

  // Fallback: cache disabled (CACHE_TTL=0) or no _cacheHash — original path untouched.
  try {
-    const content = await upstreamCall(model, messages, conversationId, req._authKeyName);
+    const content = await upstreamCall(model, messages, conversationId, req._authKeyName, res);
    const id = `chatcmpl-${randomUUID()}`;
    completionResponse(res, id, model, content);
    try { recordUsage({ keyId: req._authKeyId, keyName: req._authKeyName, model, promptChars, responseChars: content.length, elapsedMs: Date.now() - t0Usage, success: true }); } catch (e) { logEvent("error", "usage_record_failed", { error: e.message }); }
  } catch (err) {
+    // L1: disconnect-while-queued — same quiet non-error outcome as the singleflight
+    // path above and the streaming path (see acquireClaudeSlot's info-level log).
+    if (err instanceof RequestDisconnectedError) { try { res.end(); } catch {} return; }
    try { recordUsage({ keyId: req._authKeyId, keyName: req._authKeyName, model, promptChars, responseChars: 0, elapsedMs: Date.now() - t0Usage, success: false }); } catch (e) { logEvent("error", "usage_record_failed", { error: e.message }); }
    console.error(`[proxy] error: ${err.message}`);
    if (res.headersSent || res.writableEnded || res.destroyed) {
@@ -2273,11 +2603,22 @@ const server = createServer(async (req, res) => {
      spawn: (() => {
        if (TUI_MODE) return { mode: "tui (default -p path unused)", isolated: false, home: null };
        const shm = getSpawnHomeMode();
+        // FIX F6: report the EFFECTIVE current decision, not just token PRESENCE. During the
+        // 5-min pre-expiry window the token exists (shm.isolated=true) but resolveSpawnToken()
+        // returns null and spawns actually run real-HOME — so `isolated` MUST also reflect the
+        // expiry gate, or /health lies. The field SET is unchanged (grandfathered B.2 contract,
+        // ADR 0006 — HARD CONSTRAINT: no field add/remove/rename); only the VALUES are made
+        // truthful. resolveSpawnToken() is read-only + backed by F5's 30s keychain cache → cheap.
+        const effIsolated = shm.isolated && resolveSpawnToken() !== null;
        return {
-          mode: shm.isolated ? "isolated-scratch-home" : "real-home",
-          isolated: shm.isolated,
-          home: shm.isolated ? shm.home : null,
-          reason: shm.reason,
+          mode: effIsolated ? "isolated-scratch-home" : "real-home",
+          isolated: effIsolated,
+          home: effIsolated ? shm.home : null,
+          reason: effIsolated
+            ? shm.reason
+            : (shm.isolated
+                ? "oauth token within 5-min expiry window → real-HOME fallback (self-heals on next refresh)"
+                : shm.reason),
        };
      })(),
      // ── FIX ⑥ -p concurrency wait-queue surface — ADDITIVE ──
@@ -2297,9 +2638,12 @@ const server = createServer(async (req, res) => {
      // still appears with enabled:false (cheap, harmless) so the shape is stable.
      // entrypointMismatches/lastEntrypoint exist so an operator can poll /health to catch a
      // silent metered-pool drift (the audit's top risk after the 6/15 billing flip).
+      // `pool` is a NEW nested field inside the (already additive) tui block: null when the
+      // warm pool is off (the default), so the disabled shape is unchanged apart from one
+      // explicit null. Lets the operator confirm hit rate + standing process cost.
      tui: buildTuiHealthBlock(
        { enabled: TUI_MODE, entrypointMode: TUI_ENTRYPOINT, maxConcurrent: TUI_MAX_CONCURRENT },
-        tuiStats, tuiSemaphore,
+        tuiStats, tuiSemaphore, tuiPool,
      ),
    });
  }
@@ -2536,6 +2880,27 @@ function gracefulShutdown(signal) {
  if (tuiReapInterval) clearInterval(tuiReapInterval);
  closeDb();

+  // 2b. Drain the warm pane pool. A pooled `claude` is a child of the tmux SERVER, not of
+  // this node process, so it is NOT in activeProcesses and step 3 below cannot reach it —
+  // without this explicit drain every warm pane would outlive OCP as an orphan (and the
+  // pool's in-memory registry dies with the process, so nothing would remember it owned them).
+  //
+  // drain() kills the pane that is currently BOOTING too, and it does so SYNCHRONOUSLY. That
+  // is required, not incidental: step 4 below calls process.exit(0) in THIS SAME TICK whenever
+  // activeProcesses is empty — which on a TUI host it always is — so any cleanup a boot
+  // deferred to a .then()/.catch() would simply never run. (That was a real bug: the pool used
+  // to track in-flight boots as a count, could not name the booting session, and orphaned a
+  // live authenticated `claude` on every shutdown that landed mid-boot.)
+  //
+  // Orphans that survive anyway (SIGKILL, power loss) are still caught by the next instance's
+  // boot reap — this makes the graceful path clean, it is not the only safety net.
+  if (tuiPool) {
+    try {
+      const drained = tuiPool.drain();
+      if (drained) logEvent("info", "tui_pool_drained", { count: drained, trigger: "shutdown" });
+    } catch (e) { logEvent("error", "tui_pool_drain_failed", { error: e.message }); }
+  }
+
  // 3. Kill all active child processes
  for (const proc of activeProcesses) {
    try { proc.kill("SIGTERM"); } catch {}
@@ -2605,8 +2970,20 @@ server.listen(PORT, BIND_ADDRESS, () => {
      ? (TUI_HOME === process.env.HOME ? "env-token (real home — unset OCP_TUI_HOME for credential isolation)" : "env-token (credential-isolated home — no credentials.json)")
      : "credentials.json (no CLAUDE_CODE_OAUTH_TOKEN — see Troubleshooting #401)";
    console.log(`  TUI-mode: ON home=${TUI_HOME} cwd=${TUI_CWD} auth=${tuiAuth} wallclock=${TUI_WALLCLOCK_MS}ms maxConcurrent=${TUI_MAX_CONCURRENT}`);
+    console.log(TUI_POOL_SIZE > 0
+      ? `  TUI warm pool: ON size=${TUI_POOL_SIZE} — ${TUI_POOL_SIZE} idle \`claude\` process(es) held warm; first request per model is still a cold MISS`
+      : `  TUI warm pool: OFF (set OCP_TUI_POOL_SIZE=1..${POOL_MAX_SIZE} to pre-boot panes and cut ~3-4s per request)`);
    try {
-      const n = reapStaleTuiSessions();
+      // F7 fix: scope to THIS instance's own port (see reapStaleTuiSessions). includeLegacy:
+      // true ONLY here — the one-time boot reap is the designated point to claim orphaned
+      // bare-prefix ("ocp-tui-<uuid8>") zombie sessions left by a PRE-fix process generation
+      // of this same instance (no live post-fix instance ever creates that shape again).
+      // No `spare`: the warm pool is EMPTY at boot (there is no boot-time pre-warm — the pool
+      // learns its model from the first request), so this reap has no live pane to protect and
+      // it is exactly what SHOULD claim any ocp-tui-<port>-p* pool orphans left by a previous
+      // process generation of this instance (POOL/REAPER INVARIANT property 2). If a future
+      // change ever pre-warms at boot, this call MUST start passing tuiPool.liveNames().
+      const n = reapStaleTuiSessions({ port: PORT, includeLegacy: true });
      if (n) logEvent("info", "tui_reaped_stale_sessions", { count: n });
    } catch {}
  }