docs(readme): review nit — 'pre-v3.22' → 'pre-flag' (next version not fixed yet)

Reviewer nit from the Iron Rule 10 independent review of PR #156.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VqgWJcjxrjjL9L9SkpZyXR

CHANGELOG.md

@@ -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.

README.md

@@ -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,6 +958,7 @@ 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_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. |

docs/plans/2026-07-13-tui-latency/README.md

@@ -0,0 +1,190 @@
+# TUI-mode latency: measured floor, and the four things worth fixing
+
+**Date**: 2026-07-13
+**Status**: findings + backlog (no code changed yet)
+**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.
+
+---
+
+## ⚠️ 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 — **the big one (~20 s)**
+
+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; know the floor**
+
+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.

docs/plans/2026-07-13-tui-latency/billing-banner.txt

@@ -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

docs/plans/2026-07-13-tui-latency/floor.sh

@@ -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

docs/plans/2026-07-13-tui-latency/measurements.jsonl

@@ -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}

keys.mjs

@@ -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(() => {

lib/tui/semaphore.mjs

@@ -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 {

lib/tui/session.mjs

@@ -377,12 +377,38 @@ 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(" ");
 }
 

package.json

@@ -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": {

server.mjs

@@ -43,7 +43,7 @@ import { DEFAULT_PORT } from "./lib/constants.mjs";
 import { isLoopbackBind } from "./lib/net.mjs";
 import { runTuiTurn, reapStaleTuiSessions, resolveTuiHome } 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 { createSerialMutex, createTtlCache, isTokenExpiring, orderLabelsLastGoodFirst } from "./lib/spawn-auth.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -507,16 +507,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,
@@ -526,6 +571,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() {
@@ -1135,14 +1181,29 @@ 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();
-  // F3: resolve the per-spawn HOME/token decision (may serialize on the real-HOME fallback mutex).
-  const spawnDecision = await resolveSpawnDecision();
+  // 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 {
@@ -1221,28 +1282,50 @@ 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,
-    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,
-  }).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,
+    });
     // ── 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
@@ -1277,10 +1360,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) ────────────────────────────────
@@ -1326,18 +1411,30 @@ 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" } });
   }
 
-  // F3: resolve the per-spawn HOME/token decision (may serialize on the real-HOME fallback mutex).
-  const spawnDecision = await resolveSpawnDecision();
+  // 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 {
+    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);
@@ -2009,9 +2106,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;
@@ -2168,7 +2268,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 }); }
         }
@@ -2205,15 +2305,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) {
@@ -2226,11 +2338,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) {

test-features.mjs

@@ -463,6 +463,52 @@ async function runSingleflightTests() {
     assert.equal(r1, 1);
     assert.equal(r2, 2);
   });
+
+  // 7. M1: leader disconnect while queued must not poison live followers. server.mjs passes
+  // retryIf = (err) => err instanceof RequestDisconnectedError && !res.destroyed — here we
+  // model that with a tagged error class. The leader (no retryIf on its own promise — the
+  // rejection is ITS OWN disconnect) sees the error; the live follower re-executes its OWN
+  // fn and gets a real result instead of a spurious inherited failure.
+  await asyncTest("M1: leader disconnects while queued → live follower re-executes and gets a real result", async () => {
+    class FakeDisconnectError extends Error {}
+    const leaderGate = Promise.withResolvers();
+    let leaderRuns = 0;
+    let followerRuns = 0;
+    const leaderFn = async () => { leaderRuns++; await leaderGate.promise; throw new FakeDisconnectError("leader client gone"); };
+    const followerFn = async () => { followerRuns++; return "real-execution"; };
+    const retryIf = (err) => err instanceof FakeDisconnectError;
+
+    const leaderP = singleflight("sf-m1-leader-dc", leaderFn);             // becomes leader
+    const followerP = singleflight("sf-m1-leader-dc", followerFn, retryIf); // joins as follower
+    leaderGate.resolve(); // leader "disconnects" while holding the flight
+
+    await assert.rejects(leaderP, FakeDisconnectError, "the leader itself still sees its own disconnect");
+    assert.equal(await followerP, "real-execution", "follower got a REAL execution, not the leader's disconnect");
+    assert.equal(leaderRuns, 1, "leader fn ran once");
+    assert.equal(followerRuns, 1, "follower re-executed exactly once (as the new leader)");
+    assert.equal(getInflightStats().inflight, 0, "map fully cleaned up after the retry flight settles");
+  });
+
+  // 8. M1 guard: a follower whose retryIf returns false (server.mjs: its OWN client is also
+  // gone) inherits the rejection unchanged — no retry, no masked error. And a follower with
+  // NO retryIf keeps the exact pre-M1 share-everything behavior (test 2 pins the fan-out;
+  // this pins the predicate=false path specifically for the disconnect error).
+  await asyncTest("M1: follower with retryIf=false (own client also gone) inherits the leader's rejection, no retry", async () => {
+    class FakeDisconnectError extends Error {}
+    const gate = Promise.withResolvers();
+    let followerRuns = 0;
+    const leaderFn = async () => { await gate.promise; throw new FakeDisconnectError("leader client gone"); };
+    const followerFn = async () => { followerRuns++; return "should-never-run"; };
+
+    const leaderP = singleflight("sf-m1-both-dc", leaderFn);
+    const followerP = singleflight("sf-m1-both-dc", followerFn, () => false); // own client dead → no retry
+    gate.resolve();
+
+    await assert.rejects(leaderP, FakeDisconnectError);
+    await assert.rejects(followerP, FakeDisconnectError, "rejection propagates unchanged when retryIf says no");
+    assert.equal(followerRuns, 0, "follower fn never executed — no wasted spawn for a dead client");
+    assert.equal(getInflightStats().inflight, 0);
+  });
 }
 
 await runSingleflightTests();
@@ -1749,6 +1795,65 @@ test("buildTuiCmd shq-escapes a token containing shell metacharacters (no inject
   }
 });
 
+// OCP_TUI_EFFORT (TUI latency, docs/plans/2026-07-13-tui-latency): the pane's claude
+// must get an EXPLICIT --effort so its effort never depends on which HOME mode
+// resolveTuiHome() picked (real-home inherits the operator's settings.json effortLevel;
+// env-token scratch inherits claude's built-in default).
+test("buildTuiCmd passes --effort low by default (OCP_TUI_EFFORT unset)", () => {
+  const save = process.env.OCP_TUI_EFFORT;
+  try {
+    delete process.env.OCP_TUI_EFFORT;
+    const cmd = buildTuiCmd("/usr/bin/claude", "m", "sid-eff1", "/home/u", "cli");
+    assert.ok(cmd.includes("--effort low"), "default must pin --effort low");
+  } finally {
+    if (save === undefined) delete process.env.OCP_TUI_EFFORT;
+    else process.env.OCP_TUI_EFFORT = save;
+  }
+});
+
+test("buildTuiCmd honors an explicit OCP_TUI_EFFORT level (case/space-normalized)", () => {
+  const save = process.env.OCP_TUI_EFFORT;
+  try {
+    process.env.OCP_TUI_EFFORT = " XHigh ";
+    const cmd = buildTuiCmd("/usr/bin/claude", "m", "sid-eff2", "/home/u", "cli");
+    assert.ok(cmd.includes("--effort xhigh"), "explicit level must be passed, normalized");
+    assert.ok(!cmd.includes("--effort low"), "default must not also appear");
+  } finally {
+    if (save === undefined) delete process.env.OCP_TUI_EFFORT;
+    else process.env.OCP_TUI_EFFORT = save;
+  }
+});
+
+test("buildTuiCmd OCP_TUI_EFFORT=inherit omits --effort entirely (pre-flag argv)", () => {
+  const save = process.env.OCP_TUI_EFFORT;
+  try {
+    process.env.OCP_TUI_EFFORT = "inherit";
+    const cmd = buildTuiCmd("/usr/bin/claude", "m", "sid-eff3", "/home/u", "cli");
+    assert.ok(!/--effort/.test(cmd), "inherit must not add --effort");
+  } finally {
+    if (save === undefined) delete process.env.OCP_TUI_EFFORT;
+    else process.env.OCP_TUI_EFFORT = save;
+  }
+});
+
+test("buildTuiCmd falls back to --effort low on an invalid OCP_TUI_EFFORT (never reaches argv)", () => {
+  const save = process.env.OCP_TUI_EFFORT;
+  const savedErr = console.error;
+  try {
+    process.env.OCP_TUI_EFFORT = "ludicrous'; rm -rf /;'";
+    let warned = "";
+    console.error = (...a) => { warned = a.join(" "); };
+    const cmd = buildTuiCmd("/usr/bin/claude", "m", "sid-eff4", "/home/u", "cli");
+    assert.ok(cmd.includes("--effort low"), "invalid value must fall back to low");
+    assert.ok(!cmd.includes("ludicrous"), "invalid raw value must NOT reach the shell string");
+    assert.ok(/invalid OCP_TUI_EFFORT/.test(warned), "must log a warning");
+  } finally {
+    console.error = savedErr;
+    if (save === undefined) delete process.env.OCP_TUI_EFFORT;
+    else process.env.OCP_TUI_EFFORT = save;
+  }
+});
+
 test("buildTuiCmd OCP_TUI_FULL_TOOLS=1 grants -p-equivalent tool surface (single-user opt-in)", () => {
   const save = { ...process.env };
   const restore = () => {
@@ -2005,7 +2110,7 @@ test("resolveTuiHome: explicit OCP_TUI_HOME wins regardless of env token (back-c
 });
 
 // ── TUI concurrency limiter + drift observability (PR-B: audit C-4 / C-5) ──
-import { TuiSemaphore, recordTuiEntrypoint, buildTuiHealthBlock } from "./lib/tui/semaphore.mjs";
+import { TuiSemaphore, SemaphoreAbortError, recordTuiEntrypoint, buildTuiHealthBlock } from "./lib/tui/semaphore.mjs";
 
 console.log("\nTUI concurrency limiter (C-4):");
 
@@ -2110,6 +2215,226 @@ await asyncTest("FIX ⑥: slot released on normal completion is immediately reus
   assert.equal(sem.inflight, 0);
 });
 
+// ── Audit F1 — runtime-lowered/raised limit must actually bite ──────────────
+// server.mjs reuses this same TuiSemaphore as `claudeSemaphore`; a PATCH /settings
+// maxConcurrent update now calls `claudeSemaphore.setLimit(value)` (see applySettingUpdate's
+// "maxConcurrent" case). These tests pin the semaphore-level contract that fix depends on.
+console.log("\nF1 — runtime concurrency-limit changes (setLimit / release honoring the current limit):");
+
+await asyncTest("F1: lowering the limit mid-load — release() stops re-granting until inflight drains under the new limit", async () => {
+  const sem = new TuiSemaphore(3, { maxQueue: 16 });
+  const g = [deferred(), deferred(), deferred()];
+  const held = g.map((d) => sem.run(async () => { await d.p; }));
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.inflight, 3, "3 tasks hold the 3 slots");
+  // A 4th arrives while at capacity — it queues.
+  const g4 = deferred();
+  const queued4 = sem.run(async () => { await g4.p; });
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.queued, 1, "4th request queued");
+
+  // Operator lowers maxConcurrent from 3 to 1 while all 3 original slots are still inflight
+  // (mirrors a PATCH /settings maxConcurrent=1 hitting server.mjs mid-burst).
+  sem.setLimit(1);
+  assert.equal(sem.limit, 1);
+
+  // Releasing one of the 3 original holders must NOT hand the freed slot to the queued 4th
+  // request — before the F1 fix, release() handed slots off unconditionally, so inflight
+  // would have stayed pinned at the OLD higher occupancy forever.
+  g[0].resolve();
+  await held[0];
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.inflight, 2, "inflight drains toward the new limit, not re-granted");
+  assert.equal(sem.queued, 1, "4th request is STILL queued — not over-admitted");
+
+  g[1].resolve();
+  await held[1];
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.inflight, 1, "inflight now exactly at the new limit (1)");
+  assert.equal(sem.queued, 1, "still queued — inflight(1) is not < limit(1), so no grant yet");
+
+  // Releasing the LAST original holder finally drops inflight under the new limit — only
+  // now does the queued 4th request get granted.
+  g[2].resolve();
+  await held[2];
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.inflight, 1, "queued 4th request now holds the single slot");
+  assert.equal(sem.queued, 0, "queue drained");
+  g4.resolve();
+  await queued4;
+  assert.equal(sem.inflight, 0);
+});
+
+await asyncTest("F1: raising the limit wakes queued waiters immediately, up to the new headroom", async () => {
+  const sem = new TuiSemaphore(1, { maxQueue: 16 });
+  const g1 = deferred();
+  const t1 = sem.run(async () => { await g1.p; }); // holds the only slot
+  await new Promise((r) => setImmediate(r));
+  const started = [];
+  const g2 = deferred(), g3 = deferred();
+  const t2 = sem.run(async () => { started.push(2); await g2.p; });
+  const t3 = sem.run(async () => { started.push(3); await g3.p; });
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.queued, 2, "both queue behind the single holder");
+  assert.deepEqual(started, [], "neither queued task has started");
+
+  // Operator raises maxConcurrent from 1 to 3 (2 units of new headroom) — BOTH queued
+  // waiters must be woken immediately, without waiting for t1 to release.
+  sem.setLimit(3);
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.inflight, 3, "t1 + both newly-woken waiters now hold slots");
+  assert.equal(sem.queued, 0, "queue drained by the limit raise");
+  assert.deepEqual(started.sort(), [2, 3], "both queued tasks started without waiting for t1's release");
+
+  g1.resolve(); g2.resolve(); g3.resolve();
+  await Promise.all([t1, t2, t3]);
+  assert.equal(sem.inflight, 0);
+});
+
+await asyncTest("F1: raising the limit wakes only as many waiters as the new headroom allows (FIFO)", async () => {
+  const sem = new TuiSemaphore(1, { maxQueue: 16 });
+  const g1 = deferred();
+  const t1 = sem.run(async () => { await g1.p; });
+  await new Promise((r) => setImmediate(r));
+  const started = [];
+  const g2 = deferred(), g3 = deferred();
+  const t2 = sem.run(async () => { started.push(2); await g2.p; });
+  const t3 = sem.run(async () => { started.push(3); await g3.p; });
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.queued, 2);
+
+  sem.setLimit(2); // only 1 unit of new headroom (1 -> 2) — exactly one queued waiter wakes
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.inflight, 2);
+  assert.equal(sem.queued, 1, "one waiter still queued — only one slot of headroom existed");
+  assert.deepEqual(started, [2], "FIFO: the earlier-queued waiter (t2) wakes, not t3");
+
+  // Freeing t1's slot afterward still honors the (now current) limit of 2 via release()'s
+  // normal path — the still-queued t3 gets in once a slot actually frees.
+  g1.resolve();
+  await t1;
+  await new Promise((r) => setImmediate(r));
+  assert.deepEqual(started, [2, 3], "t3 granted once a slot frees, honoring the raised limit");
+  assert.equal(sem.queued, 0);
+
+  g2.resolve(); g3.resolve();
+  await t2; await t3;
+  assert.equal(sem.inflight, 0);
+});
+
+// ── Audit F2 — queued waiters must be cancellable on client disconnect ──────
+// server.mjs wires an AbortSignal derived from the client's res "close" event into
+// claudeSemaphore.acquire()/tuiSemaphore.acquire() (see closeSignalFor + acquireClaudeSlot /
+// callClaudeTui). These tests pin the semaphore-level cancellation contract that depends on.
+console.log("\nF2 — queued-wait cancellation via AbortSignal (client disconnect while queued):");
+
+await asyncTest("F2: aborting a QUEUED waiter rejects with SemaphoreAbortError and SPLICES it out (queued drops immediately, not just flagged)", async () => {
+  const sem = new TuiSemaphore(1, { maxQueue: 16 });
+  const g1 = deferred();
+  const t1 = sem.run(async () => { await g1.p; }); // holds the only slot
+  await new Promise((r) => setImmediate(r));
+  const controller = new AbortController();
+  const acquire2 = sem.acquire(controller.signal); // queues behind t1
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.queued, 1, "second acquire queued");
+
+  controller.abort(); // simulates the client disconnecting while still queued
+  await assert.rejects(acquire2, SemaphoreAbortError, "cancelled waiter rejects with SemaphoreAbortError");
+  assert.equal(sem.queued, 0, "cancelled waiter is REMOVED — queue length drops immediately");
+  assert.equal(sem.inflight, 1, "t1's slot is untouched by the cancellation");
+
+  // Prove the cancelled waiter never later acquires a slot: free t1's slot and confirm
+  // nobody is waiting to receive it (the queue is genuinely empty, not just decremented).
+  g1.resolve();
+  await t1;
+  assert.equal(sem.inflight, 0, "slot freed with nobody queued — the cancelled waiter never got it");
+});
+
+await asyncTest("F2: an already-aborted signal rejects acquire() immediately, never touching the wait queue", async () => {
+  const sem = new TuiSemaphore(1, { maxQueue: 16 });
+  const g1 = deferred();
+  const t1 = sem.run(async () => { await g1.p; }); // holds the only slot
+  await new Promise((r) => setImmediate(r));
+
+  const controller = new AbortController();
+  controller.abort(); // client already gone before this request ever tries to acquire
+  await assert.rejects(sem.acquire(controller.signal), SemaphoreAbortError);
+  assert.equal(sem.queued, 0, "never entered the wait queue at all");
+
+  g1.resolve(); await t1;
+});
+
+await asyncTest("F2: cancelling one queued waiter preserves FIFO order for the others", async () => {
+  const sem = new TuiSemaphore(1, { maxQueue: 16 });
+  const g1 = deferred();
+  const t1 = sem.run(async () => { await g1.p; });
+  await new Promise((r) => setImmediate(r));
+
+  const started = [];
+  const cA = new AbortController();
+  const cB = new AbortController();
+  const accA = sem.acquire(cA.signal).then(() => started.push("A"));
+  const accB = sem.acquire(cB.signal).then(() => started.push("B"));
+  const g3 = deferred();
+  const t3 = sem.run(async () => { started.push("C"); await g3.p; });
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.queued, 3, "A, B, C all queued behind t1");
+
+  cB.abort(); // B (the middle waiter) disconnects
+  await assert.rejects(accB, SemaphoreAbortError);
+  assert.equal(sem.queued, 2, "B removed; A and C remain, in original relative order");
+
+  g1.resolve();
+  await t1;
+  await new Promise((r) => setImmediate(r));
+  assert.deepEqual(started, ["A"], "A (queued first, still present) is granted next — FIFO preserved after B's removal");
+  assert.equal(sem.inflight, 1);
+  assert.equal(sem.queued, 1, "C still waiting");
+
+  sem.release(); // A was acquired directly (not via run()) — free its slot manually
+  await new Promise((r) => setImmediate(r));
+  assert.deepEqual(started, ["A", "C"], "C granted next");
+  g3.resolve();
+  await t3;
+  assert.equal(sem.inflight, 0);
+});
+
+await asyncTest("F2/L2: abort AFTER grant is a no-op — waiter keeps its slot, no rejection, slot released exactly once", async () => {
+  const sem = new TuiSemaphore(1, { maxQueue: 16 });
+  const g1 = deferred();
+  const t1 = sem.run(async () => { await g1.p; }); // holds the only slot
+  await new Promise((r) => setImmediate(r));
+
+  const controller = new AbortController();
+  let granted = false;
+  const acq = sem.acquire(controller.signal).then(() => { granted = true; });
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.queued, 1, "waiter queued behind t1");
+
+  // t1 finishes → release() shifts the waiter out and grants it the slot (waiter() detaches
+  // the abort listener before resolving).
+  g1.resolve();
+  await t1;
+  await acq;
+  assert.equal(granted, true, "waiter was granted the slot");
+  assert.equal(sem.inflight, 1, "granted waiter holds the slot");
+  assert.equal(sem.queued, 0);
+
+  // The client disconnects AFTER the grant — the abort-after-grant race. onAbort must be a
+  // no-op (the waiter is no longer in _waiters; idx===-1 guard): no rejection materializes,
+  // the queue is untouched, and the slot is still owned by the (already-resolved) acquirer.
+  controller.abort();
+  await new Promise((r) => setImmediate(r));
+  assert.equal(sem.inflight, 1, "abort after grant did NOT revoke or double-free the slot");
+  assert.equal(sem.queued, 0, "abort after grant did not corrupt queue accounting");
+
+  // The slot is released exactly once via the normal path and is immediately reusable.
+  sem.release();
+  assert.equal(sem.inflight, 0, "slot released exactly once via the normal path");
+  await sem.run(async () => {}); // prove the semaphore is fully healthy afterward
+  assert.equal(sem.inflight, 0);
+});
+
 console.log("\nTUI drift observability (C-5):");
 
 test("recordTuiEntrypoint: observed 'cli' is NOT a mismatch and sets lastEntrypoint", () => {