fix(server): drain F3 fallback queue immediately — invalidate F5 keychain cache before the serialized re-check

Follow-up to the F3/F5/F6 fix (independent-review observation). F5's 30s keychain TTL cache could make F3's post-refresh re-check see the stale (expiring) cached creds for up to ~30s, so a waiter admitted right after the prior real-HOME holder's claude refreshed the keychain would needlessly fall back to real HOME again instead of proceeding ISOLATED. Serialization safety was never at risk (still one real-HOME spawn at a time, no double-refresh); only the drain-to-fast-path optimization lagged. Fix: invalidateKeychainReadCache() clears the F5 TTL cache; resolveSpawnDecision() calls it under the fallback mutex, immediately before the re-check, so the admitted waiter reads FRESH keychain state and drains to the isolated fast path at once. The extra keychain read happens only on the rare real-HOME fallback path and only under the mutex (serialized, one at a time). Alignment: unchanged from the parent commit — proxy-internal keychain/HOME-isolation process logic, no cli.js analogue (cli.js citation DECLARED ABSENT, ALIGNMENT.md Rule 2), no endpoint/header/body, /health shape unchanged, OCP still never performs a refresh_token grant itself (#112). 249 tests pass. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
fix(server): serialize -p real-HOME token fallback + TTL-cache keychain + de-stale isolation decision (F3/F5/F6)
2026-07-22 05:25:08 +00:00 · 2026-07-07 22:43:46 +10:00 · 2026-07-07 22:39:10 +10:00 · 2026-06-26 20:35:21 +10:00 · 2026-06-25 11:50:06 +10:00 · 2026-06-25 11:26:57 +10:00
12 changed files with 1274 additions and 202 deletions
@@ -1,5 +1,42 @@
 # Changelog
 ## 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.
 ### TUI dead-code / footgun cleanup
 - **A1 — removed inert entrypoint-env path** (`lib/tui/session.mjs`): deleted `resolveTuiEntrypointEnv()` and the redundant env-strip block in `runTuiTurn`. The `{env}` object passed to `spawnSync` (tmux itself) was the wrong target — tmux does NOT forward the spawning process's environment to the pane; the pane's `claude` gets its env exclusively from the `env` prefix string built inside `buildTuiCmd` (verified live 2026-06-01). The spawnSync env is now intentionally minimal (`HOME` only). Behavior is unchanged: `buildTuiCmd` already handled all claude-specific env vars via its prefix string.
 - **A2 — removed test-only transcript helpers** (`lib/tui/transcript.mjs`): deleted `encodeCwd()` and `transcriptPath()` exports and the tests that pinned them. Production resolves transcripts exclusively via `findTranscriptPath()` (glob by session-id), which is immune to the exact path-encoding rule. No non-test importers existed (grep confirms). A `// TODO` comment near `findTranscriptPath()` notes that a CI fixture-contract test would make claude-schema drift fail loudly.
 - **A3 — removed headless-unusable `--dangerously-skip-permissions` branch** (`lib/tui/session.mjs` + `README.md`): `OCP_TUI_FULL_TOOLS=1` now always takes the `--allowedTools` path. The removed branch pushed `--dangerously-skip-permissions` when `CLAUDE_SKIP_PERMISSIONS=true`; on claude v2.1.x this triggers an interactive bypass-acceptance screen that a headless tmux pane cannot answer → the turn hangs to the wallclock cap and bricks the pane. The working path is `--allowedTools` + scratch-home `settings.json` `additionalDirectories`. `CLAUDE_SKIP_PERMISSIONS` for the `-p` path is unchanged (still used in `server.mjs`).
 ### Docs
 - **Client-tools boundary** (README `§ How It Works`): OCP is a text-prompt bridge only — it does not pass OpenAI `tools`/`functions` or Anthropic `tool_use` blocks to the client. Clients receive assistant TEXT only; client-local tool execution is not supported by design (bypassing `cli.js` = out of scope per `ALIGNMENT.md`).
 - **ToS honesty** (README `§ Deployment model & security`): pooling one Claude subscription across multiple distinct people may violate Anthropic's Consumer ToS and risk account suspension by the abuse classifier. The defensible framing is "one person, your own devices" — friends/team sharing is not. The prior language ("account terms are your call") was accurate but understated the risk.
 - **"Why OCP" posture** (README `§ Why OCP?`): new bullet making explicit that OCP drives the official `claude` CLI as-is — no OAuth token extraction, no binary patching, no protocol invention — so traffic looks like genuine Claude Code (`cc_entrypoint=cli`).
 - **Promotion plan** (`docs/PROMOTION.md`): "stable & visible" strategy covering goal (polish + low-key OSS visibility, NOT growth-hacking given the live ToS/billing risk), pre-requisites (stability first), honest ToS disclosure requirement, items explicitly skipped (multi-backend routing → OLP; gateway model-discovery; raw API passthrough → ALIGNMENT.md scope), TUI toggle as billing-split insurance, and low-key visibility actions. Framed as a recommendation for the maintainer to review, not a committed plan.
 ### Previously shipped (v3.20.x) — documented here for completeness
 - **Default `-p` spawn-home isolation** (v3.20.0 / PR-A): per-request `claude` spawns run in a credential-free minimal scratch HOME (`$HOME/.ocp/spawn-home`, no `.credentials.json`/`settings.json`/plugins) with a neutral cwd and the env token, cutting per-request latency (measured ~10–28s → ~3–7s). Kill-switch: `OCP_SPAWN_REAL_HOME=1`. Active mode shown at startup and on `/health.spawn`.
 - **Bounded concurrency wait-queue** (v3.20.0 / PR-B): excess `-p` requests queue (up to `CLAUDE_MAX_QUEUE`, default 16) instead of being rejected; a full queue returns `HTTP 429` + `Retry-After` (not an opaque 500). New env vars: `CLAUDE_MAX_QUEUE`, `CLAUDE_QUEUE_RETRY_AFTER`. Surfaced on `/health.concurrency` + `/health.stats.queueRejections`.
 - **`ocp restart`** macOS `bootout`+`bootstrap` (v3.20.0 / PR-B): safe restart command that forces launchd to re-read the plist (unlike `kickstart -k` which reuses the cached env).
 - **`/ocp` plugin OpenClaw-2026.5.27 compat** (v3.20.0 / PR-C): gateway plugin updated for the current OpenClaw API version.
 ## v3.20.1 — 2026-06-13
 TUI-mode auth hardening: fixes the recurring `Please run /login · API Error: 401` (the PI231 incident) and reaps leaked defunct `claude` sessions. ([#141](https://github.com/dtzp555-max/ocp/pull/141))
 ### Fixed
 - **TUI 401 / credential corruption (#141)** — interactive `claude` prefers `~/.claude/.credentials.json` over the `CLAUDE_CODE_OAUTH_TOKEN` env var (unlike `-p` mode, where the env token wins). OCP TUI's per-request spawn + `kill-session` cycle raced claude's single-use refresh-token rotation, corrupting the refresh token to an empty string → permanent 401 that `claude /login` couldn't fix (each new spawn re-corrupted it). This bit Linux/file-based hosts specifically (macOS reads credentials from the Keychain, so Mac mini was immune). **Fix:** when `CLAUDE_CODE_OAUTH_TOKEN` is set, the TUI claude now runs in a credential-free scratch HOME (`<HOME>/.ocp-tui/home`, overridable by `OCP_TUI_HOME`) seeded with onboarding + cwd-trust but **no `.credentials.json`**, so the env token is the only credential and claude never runs the refresh path. Recurrence-proof — a later `claude login` can no longer break TUI. Also: `buildTuiCmd` passes `CLAUDE_CODE_OAUTH_TOKEN` to the spawn, and `reapStaleTuiSessions` reaps defunct `claude` sessions (tmux-server-owned zombies) via `kill-server` when no foreign session remains, plus a 15-min idle-gated periodic reap. When the env token is unset, behaviour is byte-for-byte unchanged (real-home + credentials.json). Two independent fresh-context reviewers (Iron Rule 10) + a live PI231 portability test (works with a corrupt credentials.json present). Authorized by the ADR 0007 PR-D amendment (Class B).
 ### Environment variables
 - `CLAUDE_CODE_OAUTH_TOKEN` — when set on a TUI host, TUI authenticates via this long-lived token in a credential-isolated home (recommended; immune to credentials.json corruption).
 - `OCP_TUI_HOME` — overrides the TUI scratch home; if you previously pointed it at your real home, unset it to get the credential-isolated default.
 ## v3.20.0 — 2026-06-10
 TUI-mode billing-safety hardening for the 2026-06-15 Anthropic billing split. A 5-dimension multi-agent audit (adversarial verification + live tests on all three hosts — PI231 / Oracle / Mac mini, claude 2.1.104 / 2.1.114 / 2.1.170) found the TUI subscription-pool path could silently bill the metered Agent SDK pool or poison the cache under realistic failure modes. Three PRs, each with a fresh-context reviewer (Iron Rule 10) and CI; the default path (`CLAUDE_TUI_MODE` unset) is byte-for-byte unchanged.
@@ -31,6 +31,7 @@ There are several Claude proxy projects. OCP picks a specific lane: **align tigh
 - **SSE heartbeat for long reasoning** ([v3.12.0](https://github.com/dtzp555-max/ocp/releases/tag/v3.12.0), opt-in). If you've ever watched your IDE die at the 60s idle mark during a long Claude tool-use pause — that's nginx/Cloudflare default behavior. OCP emits an SSE comment frame to keep the connection alive without polluting the response. ([PR #49](https://github.com/dtzp555-max/ocp/pull/49))
 - **`cli.js` alignment + CI guardrail.** LLM-assisted code drifts easily — it's tempting to invent plausible-looking endpoints that `cli.js` doesn't actually use. [`ALIGNMENT.md`](./ALIGNMENT.md) is binding: every endpoint OCP exposes must cite a `cli.js` line. The [`alignment.yml`](./.github/workflows/alignment.yml) CI workflow blocks PRs that introduce known-hallucinated tokens. The payoff is boring: your setup keeps working when `cli.js` ships its next minor.
 - **`models.json` single source of truth** (v3.11.0). Adding a model is one file edit; both `/v1/models` and the OpenClaw bootstrap derive from it. ([PR #30](https://github.com/dtzp555-max/ocp/pull/30))
 - **Drives the official CLI as-is, no binary patching.** OCP spawns the official `claude` CLI (or hosts it in an interactive tmux pane for TUI mode) — it does not extract OAuth tokens from memory, patch the binary, or invent protocol extensions. Traffic therefore looks like genuine Claude Code to Anthropic's classifiers (`cc_entrypoint=cli`). See `ALIGNMENT.md` for why this constraint is load-bearing.
 ### Comparison
@@ -128,11 +129,12 @@ Before each step, tell me what you'll run and wait for confirmation.
 On any error, diagnose first — don't auto-retry.
 ```
-**LAN mode (server)** — install OCP as a server so your family or multiple devices can share it:
+**LAN mode (server)** — install OCP as a server so your own devices on the LAN can reach it (Claude Pro/Max are per-user accounts — review Anthropic's Usage Policy before extending access to other people):
 ```text
-I want to install OCP on this device as a LAN server so my family and other
+I want to install OCP on this device as a LAN server so my own devices on the
-devices on the network can share my Claude Pro/Max subscription.
+network can reach my Claude Pro/Max subscription through a local
 OpenAI-compatible endpoint.
 Please follow https://github.com/dtzp555-max/ocp/blob/main/README.md
 "Server Setup" → "LAN mode" path:
@@ -422,6 +424,7 @@ ocp keys revoke son-ipad   # Revoke a key
 - The per-key modes (`shared` / `multi`) give per-key **usage tracking, quotas, and cache separation** — useful for seeing who used what and capping budgets.
 - They do **not** give a **security isolation boundary**. The spawned `claude` runs with the **operator's filesystem access** and is *not* sandboxed per key. **Only share with people you fully trust, on a trusted network.**
 - For simple trusted family sharing, the easiest setup is a single shared **anonymous key** (see [Anonymous Access](#anonymous-access-optional)) — no per-person separation, same trust assumption.
 - **Account terms and ToS — read before sharing with others.** Claude Pro/Max are *per-user* accounts. Pooling a single subscription across **multiple distinct people** may violate Anthropic's Consumer Terms of Service and risk account suspension by the abuse classifier. The defensible framing is **"one person, your own devices"** — sharing with friends or a team is not. OCP does not change your account terms, and whether any particular sharing setup complies with the ToS is the account holder's responsibility. Review Anthropic's Usage Policy before extending access to other people.
 **Real per-user isolation (sandboxed, multi-tenant-safe) is planned for after 2026-06-15** — per-key ephemeral home + tool lockdown + an OS sandbox. Until then, treat a multi-user OCP as a *trusted-group convenience*, not a security boundary. (This is also why `CLAUDE_TUI_MODE` is single-user-only — see [Subscription-pool (TUI) mode](#subscription-pool-tui-mode).)
@@ -698,6 +701,14 @@ Your IDE → OCP (localhost:3456) → claude --output-format stream-json CLI →
 OCP translates OpenAI-compatible `/v1/chat/completions` requests into `claude --output-format stream-json` CLI calls. Anthropic sees normal Claude Code usage — no API billing, no separate key needed.
 ### Client-tools boundary
 OCP is a **text-prompt bridge** to the official `claude` CLI. It does **not** pass through OpenAI `tools`/`functions` payloads or Anthropic `tool_use` blocks to the client. Clients (Cline, Cursor, OpenClaw, etc.) pointed at OCP receive **assistant TEXT only** — they never get `tool_calls` to execute locally.
 Any tool use happens server-side, under the `--allowedTools` set configured on the OCP host. In default mode (no `CLAUDE_NO_CONTEXT`), the `claude` CLI's own built-in tools are available to the model; in TUI mode, the operator controls the tool surface via `OCP_TUI_FULL_TOOLS`. Either way, the tools run under the operator's credentials on the server, and the client sees only the final text output.
 **Client-local tool execution is not supported by design.** Supporting it would require bypassing the `claude` CLI to call the raw Anthropic API directly — that is a different product, and is out of scope per `ALIGNMENT.md` (every OCP endpoint must correspond to something `cli.js` actually does).
 ## Available Models
 | Model ID | Notes |
@@ -842,6 +853,29 @@ ocp restart
 openclaw gateway restart
 ```
 ### Env var change (e.g. `CLAUDE_BIND`, `CLAUDE_CODE_OAUTH_TOKEN`) doesn't take effect after restart
 On **macOS**, `ocp restart` does a full `launchctl bootout` + `bootstrap` of the agent, which **re-reads the plist `EnvironmentVariables`** — so an env change you made (in `~/Library/LaunchAgents/dev.ocp.proxy.plist`) actually takes effect:
 ```bash
 ocp restart
 ```
 This is deliberate: the older `launchctl kickstart -k` only re-execs the process and **reuses launchd's cached environment**, so plist env edits would be silently ignored. If you ever restart the agent by hand, use bootout+bootstrap, not `kickstart -k`:
 ```bash
 launchctl bootout   gui/$(id -u)/dev.ocp.proxy 2>/dev/null
 launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.ocp.proxy.plist
 ```
 Verify the new value reached the running process:
 ```bash
 ps -E -p "$(launchctl print gui/$(id -u)/dev.ocp.proxy 2>/dev/null | awk '/pid =/{print $3}')" | tr ' ' '\n' | grep CLAUDE_
 ```
 On **Linux**, `systemctl --user restart` already re-reads the unit's `EnvironmentFile`, so no special handling is needed.
 ### Usage shows "unknown"
 Usually caused by an expired Claude CLI session. Fix:
@@ -871,6 +905,24 @@ openclaw gateway restart   # so OpenClaw re-reads the config
 Future `ocp update` invocations sync automatically.
 ### TUI-mode returns `Please run /login · API Error: 401` (re-login doesn't stick)
 A long-running TUI-mode host can get stuck returning a permanent 401 that re-login cannot fix.
 **Root cause (two layers):** interactive `claude` **prefers `~/.claude/.credentials.json` over the `CLAUDE_CODE_OAUTH_TOKEN` env var** (this is *unlike* the `-p` path, where the env token wins). So (a) a stale/corrupt `credentials.json` **shadows** the env token — passing the token is not enough on its own; and (b) when claude does use `credentials.json`, its single-use OAuth refresh token can be corrupted (ending up an empty string) by the per-request spawn + `kill-session` teardown racing claude's token rotation. Re-login writes a fresh token, but the next spawn re-corrupts it. Proven live on PI231: *env token passed + broken `credentials.json` present → 401; env token passed + `credentials.json` moved aside → works.*
 **Fix:** set `CLAUDE_CODE_OAUTH_TOKEN` on the OCP host and leave `OCP_TUI_HOME` **unset**. OCP then runs the TUI `claude` in a **credential-isolated home** (`$HOME/.ocp-tui/home`) that has **no `credentials.json`** at all, so the env token is the only credential (authoritative — nothing shadows it) and claude never runs the refresh path (so the single-use token can't be corrupted). Then restart — on systemd `daemon-reload`, on launchd `bootout`+`bootstrap`; `kickstart -k` does **not** reload env. Verify the env reached the process and the boot log shows the isolated home:
 ```bash
 # Linux (systemd): confirm the token is in the service env
 tr '\0' '\n' < /proc/$(pgrep -f server.mjs | head -1)/environ | grep CLAUDE_CODE_OAUTH_TOKEN
 # Boot log should read: TUI-mode: ON home=$HOME/.ocp-tui/home ... auth=env-token (credential-isolated home — no credentials.json)
 ```
 > If you previously set `OCP_TUI_HOME` to the real home (or any home that contains a `credentials.json`), **unset it** so the credential-isolated default takes effect — otherwise the shadowing `credentials.json` remains in play.
 See [Subscription-pool (TUI) mode](#subscription-pool-tui-mode) and ADR 0007 PR-C / PR-D amendments.
 ## Environment Variables
 | Variable | Default | Description |
@@ -883,7 +935,9 @@ Future `ocp update` invocations sync automatically.
 | `CLAUDE_BIN` | *(auto-detect)* | Path to claude binary |
 | `CLAUDE_TIMEOUT` | `600000` | Request timeout (ms, default: 10 min) |
 | `CLAUDE_HEARTBEAT_INTERVAL` | `0` | Streaming SSE keepalive interval (ms). `0` = disabled. See "Streaming heartbeat" section. |
-| `CLAUDE_MAX_CONCURRENT` | `8` | Max concurrent claude processes |
+| `CLAUDE_MAX_CONCURRENT` | `8` | Max concurrent claude processes (`-p`/stream-json path) |
 | `CLAUDE_MAX_QUEUE` | `16` | Max requests **waiting** for a `-p` concurrency slot. Beyond `CLAUDE_MAX_CONCURRENT`, requests queue (up to this cap) instead of being rejected; when the queue is **also** full, the request gets `HTTP 429` + `Retry-After` (not an opaque 500). Surfaced on `/health.concurrency` + `/health.stats.queueRejections`. |
 | `CLAUDE_QUEUE_RETRY_AFTER` | `5` | Seconds advertised in the `Retry-After` header on a `-p` concurrency-overflow `429`. |
 | `CLAUDE_MAX_PROMPT_CHARS` | `150000` | Prompt truncation limit (chars) |
 | `CLAUDE_SESSION_TTL` | `3600000` | Session expiry (ms, default: 1 hour) |
 | `CLAUDE_CACHE_TTL` | `0` | Response cache TTL (ms, 0 = disabled). Set to e.g. `300000` for 5-min cache |
@@ -894,13 +948,15 @@ Future `ocp update` invocations sync automatically.
 | `PROXY_ANONYMOUS_KEY` | *(unset)* | Well-known anonymous key allowlist (multi mode). When set, this exact string bypasses `validateKey()` and grants public access. Exposed via `/health.anonymousKey` only to localhost, or to all callers when `PROXY_ADVERTISE_ANON_KEY=1`. See [Anonymous Access](#anonymous-access-optional). |
 | `PROXY_ADVERTISE_ANON_KEY` | *(unset)* | When `=1`, advertise `PROXY_ANONYMOUS_KEY` in the public `/health` body for remote zero-config discovery. Default off — `/health` is unauthenticated, so this exposes the shared key to any LAN-reachable device (issue #109). Localhost always sees it regardless. |
 | `CLAUDE_TUI_MODE` | `false` | **Opt-in.** Set to `"true"` to serve requests via interactive `claude` (no `-p` / `--output-format` → `cc_entrypoint=cli`, subscription pool). **Single-user only** — see [Subscription-pool (TUI) mode](#subscription-pool-tui-mode) for the security constraint. |
 | `CLAUDE_CODE_OAUTH_TOKEN` | *(unset)* | OAuth bearer token (highest-precedence credential source for the `-p` path). **Recommended for TUI-mode hosts:** when set (and `OCP_TUI_HOME` unset), OCP runs the interactive `claude` in a **credential-isolated home** (`$HOME/.ocp-tui/home`, no `credentials.json`) so this long-lived token is the only credential and is authoritative — interactive `claude` otherwise *prefers* `~/.claude/.credentials.json` over the env var, so a stale one shadows the token and its single-use refresh token gets corrupted by the spawn/teardown cycle (the permanent `Please run /login` 401 — see [Subscription-pool (TUI) mode](#subscription-pool-tui-mode) and ADR 0007 PR-D). The token appears in the pane command (ps-visible) — acceptable for the single-user A-path; the multi-user B-path is refused at boot. |
 | `OCP_SPAWN_REAL_HOME` | *(unset)* | Kill-switch for the default `-p`/stream-json **spawn-home isolation** (latency fix). When unset and an OAuth token is resolvable, OCP runs the per-request `claude` spawn in a **credential-free minimal scratch home** (`$HOME/.ocp/spawn-home`, no `.credentials.json`/`settings.json`/plugins) with a neutral cwd and the env token — so it loads none of the operator's heavy global `~/.claude` (plugins/skills/hooks) or the project `CLAUDE.md`, cutting per-request latency (measured ~10–28s → ~3–7s). Set to `"1"` to force the legacy real-`HOME` spawn (no cwd override) even when a token exists. With **no** resolvable token, OCP falls back to the real `HOME` automatically (zero regression). Active mode is shown at startup and on `/health.spawn`. |
 | `CLAUDE_TUI_WALLCLOCK_MS` | `120000` | (TUI-mode) Maximum time in ms to wait for the native transcript to signal turn completion. Increase for long Opus thinking turns. |
 | `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` | `$HOME` (real home) | (TUI-mode) `HOME` claude runs under. Default is the operator's real home (shared credentials, existing onboarding). Set to a separate path for scratch-home isolation — see ADR 0007 for the credential-fork caveat. |
+| `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_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` / `--dangerously-skip-permissions`, read from `CLAUDE_ALLOWED_TOOLS` / `CLAUDE_MCP_CONFIG` / `CLAUDE_SKIP_PERMISSIONS`) — 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.) See [Subscription-pool (TUI) mode](#subscription-pool-tui-mode) and ADR 0007. |
+| `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. |
 ### Streaming heartbeat
@@ -946,17 +1002,27 @@ mkdir -p ~/.ocp-tui/work    # one-time scratch cwd setup
 # Enable
 export CLAUDE_TUI_MODE=true
 # STRONGLY RECOMMENDED on a TUI host — authenticate via the long-lived OAuth token.
 # With this set (and OCP_TUI_HOME left UNSET), OCP runs the interactive claude in a
 # credential-isolated home ($HOME/.ocp-tui/home, no credentials.json), so the env token
 # is the only credential and is authoritative. This both stops a stale credentials.json
 # from shadowing the token AND ends the refresh-token corruption that caused a permanent
 # "Please run /login" 401 (no credentials file → claude never runs the refresh path).
 # See the auth note below + ADR 0007 PR-D.
 export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
 # Optionally tune:
 export CLAUDE_TUI_WALLCLOCK_MS=180000   # 3 min cap for long Opus turns
 export OCP_TUI_CWD=$HOME/.ocp-tui/work  # default; override if needed
 export OCP_TUI_ENTRYPOINT=cli           # default; use 'auto' to observe TTY-derived value
 # Do NOT set OCP_TUI_HOME for the recommended setup — leaving it unset is what enables
 # the credential-isolated home. Set it only to opt into the legacy symlinked-creds mode.
 ```
-Then restart OCP. At boot you will see:
+Then restart OCP. At boot you will see (with the env token set, isolated home auto-selected):
 ```
 ⚠️  TUI-mode ON — single-user only; do NOT enable on a multi-user OCP ...
-  TUI-mode: ON home=/home/user cwd=/home/user/.ocp-tui/work wallclock=120000ms
+  TUI-mode: ON home=/home/user/.ocp-tui/home cwd=/home/user/.ocp-tui/work auth=env-token (credential-isolated home — no credentials.json) wallclock=120000ms maxConcurrent=2
 ```
 ### What changes / what doesn't
@@ -965,6 +1031,8 @@ Then restart OCP. At boot you will see:
 - **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.
 - **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.
@@ -0,0 +1,100 @@
 # OCP Promotion Strategy — "Stable & Visible"
 > **This document is a recommendation for the maintainer to review and adjust, not a committed plan.**
 > It reflects the project's current posture (post-v3.21.0) and should be revisited whenever
 > the Anthropic billing / ToS environment changes significantly.
 ---
 ## 1. Goal: Polish + Low-Key OSS Visibility
 The goal is **stability and quiet discoverability**, not growth-hacking. OCP is a personal power tool
 that has been open-sourced because others can benefit from it. The right audience finds it via GitHub
 search, issue threads in related projects, and word of mouth — not viral posts.
 **Explicitly avoid:**
 - HN / Reddit front-page pushes, influencer outreach, or any campaign that would attract a large
  influx of users before the ToS/billing situation has settled. Anthropic is actively tightening
  billing and enforcement on subscription-sharing (the June-15 Agent-SDK billing split is
  *paused*, not cancelled — and consumer-ToS enforcement on multi-person sharing is a live risk).
  A high-traffic spotlight right now would draw scrutiny that a low-profile project avoids.
 - Promising features that require bypassing the `claude` CLI (raw API calls, OAuth extraction, etc.)
  — that would violate `ALIGNMENT.md` and the ToS simultaneously.
 ---
 ## 2. Pre-Requisite: Stability First
 Do not promote until the house is in order:
 - [x] The concurrency / latency perf fixes are shipped (v3.20.x–v3.21.0).
 - [x] Docs honesty is complete (client-tools boundary, ToS sharing disclosure, this doc).
 - [ ] The June-15 Agent-SDK billing split is either confirmed cancelled or OCP has a confirmed
      stable path (TUI toggle as insurance — see §5 below).
 Promoting a project that has known rough edges in docs or stability only generates support burden
 and negative first impressions.
 ---
 ## 3. Honest ToS Disclosure on Sharing
 Any promotion materials must carry the same disclosure as `README.md § "Deployment model & security"`:
 > Pooling a single Claude subscription across **multiple distinct people** may violate Anthropic's
 > Consumer Terms of Service and risk account suspension. The defensible framing is "one person,
 > your own devices". Friends/team sharing is not.
 This framing should appear in any README badge, linked blog post, or issue comment that mentions
 LAN sharing. It is not a disclaimer that discourages usage — it is honest positioning that protects
 both the project and its users.
 ---
 ## 4. What to Explicitly Skip
 These items are **not gaps in OCP** — they are deliberate stance decisions:
 - **Multi-backend routing** (routing to OpenAI, Gemini, Llama, etc.) — that is the sibling [OLP
  project](https://github.com/dtzp555-max/olp)'s role. OCP stays Claude-only by design.
 - **Gateway model-discovery** (auto-detecting which models a remote server offers) — not needed
  for OCP's single-provider, single-subscription model. `models.json` is the SPOT.
 - **Raw Anthropic API passthrough** (bypassing the `claude` CLI) — out of scope per `ALIGNMENT.md`.
 Do not add these to OCP roadmaps or respond to feature requests for them with "planned" — the
 correct answer is "that's OLP territory" or "out of scope per ALIGNMENT.md".
 ---
 ## 5. TUI Toggle as Insurance
 The `CLAUDE_TUI_MODE` opt-in is the primary mitigation if the June-15 billing split reactivates
 and makes the default `-p` path draw from the metered Agent SDK credit pool.
 Keep the TUI toggle:
 - Functional and tested across the three deployment hosts.
 - Documented in the README, including the security constraints (single-user only).
 - Easily discoverable for users who get unexpectedly metered.
 If the split reactivates, the recommended operator path is: set `CLAUDE_TUI_MODE=true` +
 `CLAUDE_CODE_OAUTH_TOKEN` → credential-isolated scratch home → subscription pool. That path is
 already shipped and documented.
 ---
 ## 6. Low-Key Visibility Actions (when §2 pre-requisites are met)
 - Keep the GitHub README polished and honest — it is the primary landing page.
 - Respond promptly to issues and PRs — the project's reputation is built on reliability, not
  marketing.
 - Add OCP to the `awesome-claude` / `awesome-llm-tools` lists if they exist and allow self-PRs
  — low-effort, targeted, reaches the right audience.
 - When related projects (Cline, OpenCode, OpenClaw, Continue.dev) post about local Claude proxies,
  a short factual comment linking to OCP is appropriate — not spam.
 - Maintain the `CHANGELOG.md` with clear, honest summaries — users who are already running OCP
  are the best vector for word-of-mouth.
 ---
 *Last updated: v3.21.0 cleanup cycle. Maintainer should re-read before any external promotion.*
@@ -1,7 +1,7 @@
 # ADR 0007 — TUI Interactive Mode (subscription-pool bridge)
 **Date:** 2026-05-31
-**Status:** Accepted — amended by PR-4 (entrypoint hardening)
+**Status:** Accepted — amended by PR-4 (entrypoint hardening), PR-B (observability + concurrency), PR-C (env-token auth + defunct-reaping), PR-D (credential-isolated home — corrects PR-C)
 **Deciders:** project maintainer
 **Authority:** claude CLI v2.1.158 interactive mode — verified live on the test host that sessions launched without `-p` / `--output-format` carry `cc_entrypoint=cli` (subscription pool), not `cc_entrypoint=sdk-cli` (Agent SDK credit pool). Mechanism verified on cli.js v2.1.104; live-confirmed on v2.1.158.
@@ -98,12 +98,16 @@ When `CLAUDE_TUI_MODE` is unset (the default), no code path touches `callClaudeT
 Unset `CLAUDE_TUI_MODE` (or set it to any value other than `"true"`) → stream-json path restored immediately on next restart.
-### Home strategy (real-home default)
+### Home strategy
-`TUI_HOME = OCP_TUI_HOME || HOME` (defaults to the operator's real home).
+> **Superseded by the PR-D amendment below for the env-token case.** As of PR-D, `TUI_HOME`
 > is computed by `resolveTuiHome()`: when `CLAUDE_CODE_OAUTH_TOKEN` is set (and `OCP_TUI_HOME`
 > is unset) the default is a **credential-free scratch home**, not the real home. The
 > descriptions below remain accurate for the **no-env-token** case and the **explicit
 > `OCP_TUI_HOME` override** case.
- **Real-home (default, `OCP_TUI_HOME` unset):** claude runs with the operator's own `~/.claude/` — shared credentials, existing onboarding, no OAuth fork risk. `ensureTuiCwdTrusted` seeds the trust record for the scratch cwd in the real `~/.claude.json` (atomic write).
+- **Real-home (default when NO env token, `OCP_TUI_HOME` unset):** claude runs with the operator's own `~/.claude/` — shared credentials, existing onboarding, no OAuth fork risk. `ensureTuiCwdTrusted` seeds the trust record for the scratch cwd in the real `~/.claude.json` (atomic write).
- **Scratch-home opt-in (`OCP_TUI_HOME=<path>`):** a dedicated `HOME` that symlinks `~/.claude/.credentials.json` from the real home (token is never copied) and seeds a stripped `~/.claude.json` (no project history, trusts only the scratch cwd). **Caveat:** claude rewrites `.credentials.json` on OAuth token refresh, replacing the symlink with a regular file — this forks the credentials. Use scratch-home only with a dedicated OAuth or for ephemeral testing.
+- **Scratch-home opt-in (`OCP_TUI_HOME=<path>`, no env token):** a dedicated `HOME` that symlinks `~/.claude/.credentials.json` from the real home (token is never copied) and seeds a stripped `~/.claude.json` (no project history, trusts only the scratch cwd). **Caveat:** claude rewrites `.credentials.json` on OAuth token refresh, replacing the symlink with a regular file — this forks the credentials. Use this legacy symlink mode only with a dedicated OAuth or for ephemeral testing. (The PR-D env-token mode avoids this caveat entirely — no credentials file to fork.)
 ### Working directory
@@ -234,6 +238,79 @@ This amendment **is** that authorization. The argument:
 ---
 ## Authentication + defunct-reaping (PR-C amendment)
 **Date:** 2026-06-13
 **Status:** Accepted — amends ADR 0007.
 **Motivation:** the PI231 production incident — TUI-mode returned `Please run /login · API Error: 401` for days; re-login never stuck.
 ### How the TUI `claude` authenticates
 The spawned interactive `claude` obtains its OAuth bearer in one of two ways, in this order of preference:
 1. **`CLAUDE_CODE_OAUTH_TOKEN` in env (PREFERRED).** If the env var is set on the OCP process, `buildTuiCmd` adds `CLAUDE_CODE_OAUTH_TOKEN=<shq-escaped token>` to the pane command's `env` prefix. claude then authenticates via this long-lived token and **never touches the credentials-refresh path**. This is the stable mode — it is exactly how the oracle and Mac-mini hosts already run (and how `server.mjs`'s own `getOAuthCredentials()` takes the same env at highest precedence). cli.js is **not** the authority here: this is a Class B, OCP-owned TUI spawn — see the Class B citation below.
 2. **`<HOME>/.claude/.credentials.json` (FALLBACK).** When the env var is unset, claude falls back to the credentials file and its short-lived access token, renewing via the single-use refresh token.
 The token MUST be set explicitly in `buildTuiCmd` because **tmux does not forward the parent process's environment to the pane** (verified live 2026-06-01 — the same reason the whole env is delivered as an `env` prefix). A token sitting in the OCP process env is invisible to the pane unless `buildTuiCmd` re-emits it.
 ### Why the fallback path corrupts (the PI231 incident)
 When the env token is absent, every per-request spawn drives claude through the credentials.json refresh path. OAuth refresh tokens are **single-use / rotating**: a refresh consumes the old refresh token and writes a new one. The per-request `kill-session` teardown can race / interrupt claude mid-rotation, and over many spawn+kill cycles the refresh token ended up an **empty string** — at which point renewal is impossible and the host returns a permanent 401. Re-login writes a fresh token, but the next spawn re-corrupts it. **Proof the env-token fix works:** on the broken PI231 host, `CLAUDE_CODE_OAUTH_TOKEN=<oat01 token> claude -p ...` returned a real answer *despite* the corrupt credentials.json (control without the env token = 401).
 **Operator guidance:** set `CLAUDE_CODE_OAUTH_TOKEN` on any TUI-mode host. The credentials.json fallback is retained only for hosts that intentionally rely on it; it is not recommended for a long-running TUI deployment.
 **Security note:** with the token in the pane command, it is visible in `ps`. This is acceptable for the **single-user A-path** (it mirrors the existing plaintext-token practice for `server.mjs`), and the **multi-user B-path is already refused at boot** (`CLAUDE_TUI_MODE=true` + `AUTH_MODE=multi` is a hard FATAL), so a guest can never reach this spawn.
 ### Defunct `<claude>` reaping
 The connected leak: 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` returns the instant the server forks the pane). Node can therefore never `waitpid()`/reap it — a SIGKILL still needs the *parent* (the tmux server) to reap. `kill-session` destroys the session but leaves the pane's `claude` (and its grandchildren) as `<defunct>` zombies that only the server reaps; over 30 days on PI231 this accumulated to **25 defunct `<claude>`** (a live `tmux kill-server` dropped it 25→3).
 The node-reachable action that *actually reaps* — rather than merely re-signalling — is to stop the tmux server: on server exit the kernel reparents survivors to init (PID 1), which reaps them. `reapStaleTuiSessions` therefore, after killing our own `ocp-tui-*` sessions, issues `kill-server` **only when no foreign session of any prefix remains** (coexistence: never disrupt a co-hosted `olp-tui-*` instance). This runs at boot (existing) and now on a 15-min periodic interval gated on TUI-mode and on the TUI path being idle (`inflight === 0 && queued === 0`) so a live turn's pane is never torn down. Residual: a request whose pane is created in the narrow window between the idle-check and `kill-server` would fail cleanly via the existing honesty gates (rare; documented in the server comment).
 ### ALIGNMENT authorization (Class B)
 Both changes are **Class B** (OCP-owned TUI spawn). `cli.js` does not perform either operation — there is no `cli.js` analogue for "how the TUI pane authenticates" or "reaping tmux-server-owned zombies"; this surface is authorized by **this ADR (0007)** per `ALIGNMENT.md`'s Class B citation requirement. No Class A wire surface, no endpoint shape, no `alignment.yml` blacklist token, and no `models.json` entry is touched.
 ---
 ## Credential-isolated home for env-token auth (PR-D amendment)
 **Date:** 2026-06-13
 **Status:** Accepted — amends ADR 0007. **Corrects** the PR-C rationale and the original "Home strategy" section's scratch-home caveat.
 **Motivation:** PR-C's env-token passing alone did **not** fix the PI231 401. Decisive live evidence (claude 2.1.104, PI231):
 | Condition | Result |
 |---|---|
 | env token passed + a broken `~/.claude/.credentials.json` present | **401** (`Please run /login · API Error: 401`) |
 | env token passed + `credentials.json` moved aside | **works** (real answer) |
 ### Corrected root cause
 **Interactive `claude` PREFERS `~/.claude/.credentials.json` over the `CLAUDE_CODE_OAUTH_TOKEN` env var.** A stale/corrupt `credentials.json` therefore **shadows** the env token. (This is *unlike* `-p` mode, where the env token wins — which is why `server.mjs`'s own `getOAuthCredentials()` is unaffected and why PR-C's premise looked sufficient.) So passing the token (PR-C, `buildTuiCmd`) is **necessary but insufficient**: the TUI `claude` must additionally run in a HOME that has **no `credentials.json`**, so the env token is the only credential and is authoritative.
 This also fixes the original incident at the **root**, more completely than PR-C claimed: with no `credentials.json` in the home, claude never runs the token-refresh path at all, so the single-use refresh token can never be rotated — and therefore never corrupted — by the spawn+`kill-session` cycle. The 25-zombie / empty-refresh-token failure mode becomes structurally impossible, not merely avoided.
 ### Decision
 When `CLAUDE_CODE_OAUTH_TOKEN` is set, the TUI `claude` runs in a **credential-free scratch home** by default:
 - `resolveTuiHome({ realHome, configuredHome, envTokenSet })` (exported from `lib/tui/session.mjs`, pure) decides the home:
  - **`OCP_TUI_HOME` set** → that path (explicit override, back-compat — an operator who configured it keeps exactly that home).
  - **else env token set** → `<realHome>/.ocp-tui/home` — a dedicated scratch home seeded with a minimal `.claude.json` (`hasCompletedOnboarding=true` + trust **only** the scratch cwd) and its own `projects/` dir, and **deliberately NO `.credentials.json`** (no symlink, no copy).
  - **else (no env token)** → the operator's real home — **byte-for-byte the pre-fix behaviour** for hosts that intentionally rely on `credentials.json`.
 - `prepareTuiHome(realHome, tuiHome, cwd, { envTokenMode })` gates the credential handling: in `envTokenMode` it creates the scratch `projects/` dir and seeds the minimal trusted `.claude.json` but **never** creates the credentials symlink. `runTuiTurn` sets `envTokenMode = !!CLAUDE_CODE_OAUTH_TOKEN && ehome !== realHome`.
 - `readTuiTranscript` reads from the **same** home claude runs under (`ehome`), so transcripts land under `<scratch home>/.claude/projects/` and `findTranscriptPath` globs them there — the home is threaded through consistently. (We chose scratch-`HOME` over `CLAUDE_CONFIG_DIR`: the binary supports `CLAUDE_CONFIG_DIR`, but it relocates the transcript root to `<CONFIG_DIR>/projects/` rather than `<HOME>/.claude/projects/`, which would fork the transcript-resolution rule across modes for no benefit. The scratch-HOME lever reuses the existing, tested `prepareTuiHome`/`ehome` plumbing.)
 ### This RESOLVES — not reintroduces — the scratch-home caveat
 The original "Home strategy" section and PR-C's `prepareTuiHome` comment warned that scratch-home is unsafe because *claude rewrites a **symlinked** `.credentials.json` on token refresh → forks/corrupts the OAuth credentials*. **That caveat does not apply to env-token mode**: there is no `credentials.json` in the home to fork, and claude never refreshes (it uses the long-lived env token), so there is no rotation and no corruption. The fork risk was inherent to the *symlink* approach; removing the credentials file entirely removes the risk. The legacy symlink mode is retained **only** for an operator who explicitly sets `OCP_TUI_HOME` without an env token, and its caveat is preserved for exactly that path.
 ### ALIGNMENT authorization (Class B)
 **Class B** (OCP-owned TUI spawn). `cli.js` has no analogue for the TUI pane's auth/home strategy; authorized by **this ADR (0007)** per `ALIGNMENT.md`'s Class B citation requirement. `server.mjs` is touched only to compute `TUI_HOME` via `resolveTuiHome()` (TUI wiring) and to surface the auth mode in the boot log — no Class A wire surface, no endpoint shape, no `alignment.yml` blacklist token, and no `models.json` entry is touched.
 ---
 ## Consequences
 ### Positive
@@ -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)];
 }
@@ -23,16 +23,44 @@ const defaultTmux = (args, 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.
 //
 // 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`
 // returns the instant the server forks the pane, so node never becomes its parent and
 // therefore can NEVER waitpid()/reap it (a SIGKILL still needs the *parent* to reap, and
 // here that parent is the tmux server). `kill-session` destroys the session but the server
 // can leave the pane's `claude` (and any grandchildren claude spawned) as `<defunct>`
 // zombies that only the server can reap. Over many per-request spawn+teardown cycles these
 // accumulate (live evidence on PI231: 25 defunct `<claude>` over 30 days; `tmux kill-server`
 // dropped it 25→3). The only node-reachable action that ACTUALLY reaps them — rather than
 // 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 } = {}) {
  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);
  let killed = 0;
-  for (const name of String(r.stdout || "").split("\n").map((s) => s.trim()).filter(Boolean)) {
+  let othersRemain = false;
  for (const name of names) {
    if (name.startsWith(SESSION_PREFIX)) {
      tmux(["kill-session", "-t", name]);
      killed++;
    } else {
      othersRemain = true; // a session we do NOT own (e.g. olp-tui-*) — 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) {
    tmux(["kill-server"]);
  }
  return killed;
 }
@@ -128,39 +156,85 @@ export function ensureTuiCwdTrusted(home, cwd) {
  } catch { /* best effort */ }
 }
-// Prepare the HOME claude runs under. Two modes:
+// Resolve the HOME the TUI `claude` runs under. Three intents, decided by the env
-//   - real-home (tuiHome === realHome OR falsy): no isolation; just trust the cwd
+// token + an explicit OCP_TUI_HOME override:
 //     in the real ~/.claude.json. Opt in by setting OCP_TUI_HOME=$HOME.
 //   - scratch-home: a dedicated HOME that reuses the real OAuth via a SYMLINKED
 //     .credentials.json, with a seeded .claude.json (onboarded real config minus
 //     the user's project history; trusts only the scratch cwd) and its own
 //     projects/ dir — so the real ~/.claude is never mutated or polluted.
 //
-// ⚠️ CREDENTIAL CAVEAT (verified live): claude rewrites .credentials.json on token
+//   - ENV-TOKEN MODE (default when CLAUDE_CODE_OAUTH_TOKEN is set AND OCP_TUI_HOME is
-// refresh, REPLACING the symlink with a regular-file copy → the scratch home then
+//     unset): a CREDENTIAL-FREE scratch home at `<realHome>/.ocp-tui/home`. There is
-// FORKS the OAuth credentials. Because OAuth refresh tokens rotate (single-use), a
+//     deliberately NO .credentials.json (no symlink, no copy), so the only credential
-// refresh in the scratch home can invalidate the token the user's real-home claude
+//     claude can find is the long-lived env token (passed by buildTuiCmd). This is what
-// relies on. Therefore scratch-home is safe only with a DEDICATED OAuth or for
+//     actually FORCES env-token auth — see the prepareTuiHome comment for why passing
-// ephemeral use; for a shared subscription prefer real-home (tuiHome===realHome),
+//     the token alone is insufficient.
-// which shares one .credentials.json — identical to how OCP already spawns claude.
+//   - EXPLICIT OVERRIDE: whatever OCP_TUI_HOME names (back-compat; an operator who set it
-// Idempotent + best-effort: any failure degrades toward the dialog/cap, never
+//     keeps exactly that home).
-// corrupts. Run BEFORE the session boots.
+//   - REAL-HOME (default when the env token is unset): the operator's real home, shared
-export function prepareTuiHome(realHome, tuiHome, cwd) {
+//     credentials.json — byte-for-byte the pre-fix behaviour for credentials.json hosts.
 //
 // Pure + deterministic so server.mjs and the tests share one decision. `configuredHome`
 // is the raw OCP_TUI_HOME value (undefined/empty => unset).
 export const DEFAULT_TUI_SCRATCH_HOME = (realHome) => `${realHome}/.ocp-tui/home`;
 export function resolveTuiHome({ realHome, configuredHome, envTokenSet }) {
  if (configuredHome) return configuredHome;            // explicit override wins (back-compat)
  if (envTokenSet) return DEFAULT_TUI_SCRATCH_HOME(realHome); // credential-free scratch
  return realHome;                                       // legacy real-home default
 }
 // Prepare the HOME claude runs under. Three modes:
 //   - real-home (tuiHome === realHome OR falsy): no isolation; just trust the cwd
 //     in the real ~/.claude.json. The legacy default when no env token is set.
 //   - ENV-TOKEN scratch-home (envTokenMode === true): a dedicated HOME with a seeded
 //     .claude.json (onboarded + trusts only the scratch cwd) and its own projects/ dir,
 //     and DELIBERATELY NO .credentials.json (no symlink, no copy). claude then has no
 //     credentials file to read, so it authenticates via CLAUDE_CODE_OAUTH_TOKEN (passed
 //     by buildTuiCmd) — which is authoritative precisely because nothing shadows it.
 //   - legacy scratch-home (envTokenMode falsy, tuiHome !== realHome): the historical
 //     mode that SYMLINKS the real .credentials.json. Retained only for an operator who
 //     explicitly set OCP_TUI_HOME without an env token; see the caveat below.
 //
 // WHY ENV-TOKEN MODE IS THE FIX (proven live on PI231, claude 2.1.104):
 //   env token passed + a broken ~/.claude/.credentials.json present → 401.
 //   env token passed + credentials.json moved aside              → real answer.
 // Interactive `claude` PREFERS .credentials.json over the env var (unlike `-p`, where the
 // env token wins), so a stale/corrupt credentials.json SHADOWS the env token. Passing the
 // token is necessary but insufficient; the TUI claude must run in a HOME with NO
 // credentials.json so the env token is the only credential. This ALSO ends the refresh-
 // corruption incident at the root: with no credentials file, claude never runs the token-
 // refresh path, so the single-use refresh token can never be rotated (and corrupted) by the
 // spawn+kill cycle. (This RESOLVES — not reintroduces — the ADR 0007 scratch-home concern:
 // the old caveat was about a SYMLINKED credentials.json being forked on refresh; here there
 // is no credentials file to fork and no refresh ever happens.)
 //
 // ⚠️ LEGACY SCRATCH-HOME CAVEAT (envTokenMode falsy, symlink path): claude rewrites
 // .credentials.json on token refresh, REPLACING the symlink with a regular-file copy → the
 // scratch home FORKS the OAuth credentials and a refresh can invalidate the real-home token.
 // That path is therefore safe only with a DEDICATED OAuth or for ephemeral use. The env-token
 // mode above avoids this entirely.
 //
 // Idempotent + best-effort: any failure degrades toward the dialog/cap, never corrupts.
 // Run BEFORE the session boots.
 export function prepareTuiHome(realHome, tuiHome, cwd, { envTokenMode = false } = {}) {
  if (!tuiHome || tuiHome === realHome) { ensureTuiCwdTrusted(realHome, cwd); return; }
  try {
    const claudeDir = `${tuiHome}/.claude`;
    mkdirSync(`${claudeDir}/projects`, { recursive: true });
-    // Symlink the real credentials (never copy the OAuth token); refresh if missing.
+    if (!envTokenMode) {
-    const link = `${claudeDir}/.credentials.json`;
+      // Legacy mode ONLY: symlink the real credentials (never copy the token); refresh if
-    if (!existsSync(link)) {
+      // missing. Env-token mode deliberately skips this — no credentials file at all.
-      try { symlinkSync(`${realHome}/.claude/.credentials.json`, link); } catch { /* best effort */ }
+      const link = `${claudeDir}/.credentials.json`;
      if (!existsSync(link)) {
        try { symlinkSync(`${realHome}/.claude/.credentials.json`, link); } catch { /* best effort */ }
      }
    }
-    // Seed .claude.json ONCE (if absent): start from the onboarded real config,
+    // Seed .claude.json ONCE (if absent): onboarded + trust ONLY the scratch cwd.
-    // drop the user's project history, trust only the scratch cwd. mode 0600.
+    // In env-token mode start from a MINIMAL config (do NOT copy the real ~/.claude.json —
    // a credential-isolated home should not inherit the operator's account/config state);
    // in legacy mode carry the onboarded real config minus the user's project history.
    const seedPath = `${tuiHome}/.claude.json`;
    if (!existsSync(seedPath)) {
      let base = {};
-      try { base = JSON.parse(readFileSync(`${realHome}/.claude.json`, "utf8")); } catch { /* fresh */ }
+      if (!envTokenMode) {
        try { base = JSON.parse(readFileSync(`${realHome}/.claude.json`, "utf8")); } catch { /* fresh */ }
      }
      base.hasCompletedOnboarding = true;
      base.projects = { [cwd]: { hasTrustDialogAccepted: true, allowedTools: [] } };
      writeFileSync(seedPath, JSON.stringify(base, null, 2), { mode: 0o600 });
@@ -170,23 +244,6 @@ export function prepareTuiHome(realHome, tuiHome, cwd) {
  ensureTuiCwdTrusted(tuiHome, cwd);
 }
 // ── Billing-classifier labeling ─────────────────────────────────────────
 // Resolve CLAUDE_CODE_ENTRYPOINT on the spawn env per mode. ALWAYS deletes any
 // inherited value first (so a stray entrypoint from OCP's own parent env can never
 // leak into / mislabel the billing header). Then:
 //   "cli"  (default) → set "cli": deterministic subscription-pool classification.
 //          HONEST ONLY because OCP's spawn is a genuine interactive PTY (tmux pane,
 //          no -p, stdout not redirected). Never set "cli" on a non-interactive spawn.
 //   "auto" → leave unset → claude self-classifies via its t$A (TTY → cli). Use to
 //          observe/diagnose the real TTY-derived value.
 //   "off"  → leave the env exactly as inherited (diagnostics / honesty audit).
 export function resolveTuiEntrypointEnv(env, mode = "cli") {
  if (mode === "off") return env;
  delete env.CLAUDE_CODE_ENTRYPOINT;
  if (mode === "cli") env.CLAUDE_CODE_ENTRYPOINT = "cli";
  return env;
 }
 // Build interactive claude argv: NO -p, NO --output-format (=> cc_entrypoint=cli).
 // MCP hard-disabled: --strict-mcp-config (no --mcp-config) is the only mechanism
 // that stops account-attached managed MCP from connecting (spec §5.2 / T6),
@@ -217,6 +274,27 @@ export function buildTuiCmd(claudeBin, model, sessionId, ehome, entrypointMode)
    "CLAUDE_CODE_DISABLE_CLAUDE_MDS=1",
    "CLAUDE_CODE_DISABLE_AUTO_MEMORY=1",
  ];
  // CLAUDE_CODE_OAUTH_TOKEN: tmux does NOT forward the parent process's env to the pane (the
  // same reason the whole env is delivered as an `env` prefix above — verified live 2026-06-01),
  // so the token MUST be set explicitly here or the spawned `claude` never sees it. Without it,
  // the TUI claude falls back to authenticating via <HOME>/.claude/.credentials.json, whose
  // single-use refresh token gets corrupted by the per-request spawn + `kill-session` teardown
  // racing claude's token-rotation write (the PI231 incident: refresh token ended up an empty
  // string → permanent 401 "Please run /login", re-login re-corrupted on the next spawn). With
  // the long-lived OAuth token in env, claude authenticates via the token and never touches the
  // credentials.json refresh path — matching how the stable oracle / Mac-mini hosts already run.
  //
  // SECURITY: the token appears in the pane command (ps-visible). This is acceptable for the
  // single-user A-path — it mirrors the existing plaintext-token practice (server.mjs reads the
  // same CLAUDE_CODE_OAUTH_TOKEN env at getOAuthCredentials()), and the multi-user B-path is
  // already refused at boot (TUI + AUTH_MODE=multi is a hard FATAL). Read from process.env here,
  // consistent with how buildTuiCmd already reads OCP_TUI_FULL_TOOLS / CLAUDE_ALLOWED_TOOLS below.
  //
  // When the env is unset (e.g. a host that intentionally relies on credentials.json), no token
  // is added — behaviour is byte-for-byte unchanged from before this fix.
  if (process.env.CLAUDE_CODE_OAUTH_TOKEN) {
    sets.push(`CLAUDE_CODE_OAUTH_TOKEN=${shq(process.env.CLAUDE_CODE_OAUTH_TOKEN)}`);
  }
  const unset = ["CLAUDECODE", "ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN"];
  if (entrypointMode === "cli") sets.push("CLAUDE_CODE_ENTRYPOINT=cli");
  else if (entrypointMode === "auto") unset.push("CLAUDE_CODE_ENTRYPOINT"); // let claude self-classify via TTY
@@ -226,27 +304,24 @@ export function buildTuiCmd(claudeBin, model, sessionId, ehome, entrypointMode)
  //   DEFAULT (safe): hard-disable MCP (--strict-mcp-config + --disallowedTools mcp__*);
  //     built-in tools stay on, acceptable for single-user A-path.
  //   OCP_TUI_FULL_TOOLS=1: grant the SAME tool surface as the -p A-path
-  //     (--allowedTools [+ --mcp-config] [+ --dangerously-skip-permissions]), so a
+  //     (--allowedTools [+ --mcp-config]), so a SINGLE-USER / trusted TUI deployment can
-  //     SINGLE-USER / trusted TUI deployment can run a tool-using agent (e.g. an OpenClaw
+  //     run a tool-using agent (e.g. an OpenClaw assistant that needs Bash/Read/Write/MCP)
-  //     assistant that needs Bash/Read/Write/MCP) on the subscription pool. This mirrors
+  //     on the subscription pool. ALWAYS uses --allowedTools (CLAUDE_SKIP_PERMISSIONS /
-  //     buildCliArgs() in server.mjs. Safe to gate ON only because TUI is hard-incompatible
+  //     --dangerously-skip-permissions is intentionally removed: claude v2.1.x shows an
-  //     with AUTH_MODE=multi (server.mjs refuses to boot), so it can never widen a guest's
+  //     interactive bypass-acceptance screen in headless tmux that nothing can answer →
-  //     surface. Env mirrors server.mjs's CLAUDE_ALLOWED_TOOLS / _SKIP_PERMISSIONS / _MCP_CONFIG.
+  //     the turn hangs until the wallclock cap, bricks the pane; not recoverable without a
  //     human at a keyboard). Use scratch-home settings.json additionalDirectories instead.
  let toolArgs;
  if (process.env.OCP_TUI_FULL_TOOLS === "1") {
    toolArgs = [];
-    if (process.env.CLAUDE_SKIP_PERMISSIONS === "true") {
+    const allowed = (process.env.CLAUDE_ALLOWED_TOOLS ||
-      toolArgs.push("--dangerously-skip-permissions");
+      "Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch,Agent")
-    } else {
+      .split(",").map((s) => s.trim()).filter(Boolean);
-      const allowed = (process.env.CLAUDE_ALLOWED_TOOLS ||
+    // shq EACH token: buildTuiCmd returns a SHELL STRING (run by tmux via sh -c), unlike
-        "Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch,Agent")
+    // buildCliArgs which returns an argv array to spawn(). claude accepts scoped specifiers
-        .split(",").map((s) => s.trim()).filter(Boolean);
+    // like "Bash(npm run test:*)" / "Read(~/**)" whose ( ) * ~ would break/inject the shell
-      // shq EACH token: buildTuiCmd returns a SHELL STRING (run by tmux via sh -c), unlike
+    // command if pasted bare. (operator-self-injection only — guests can't reach TUI.)
-      // buildCliArgs which returns an argv array to spawn(). claude accepts scoped specifiers
+    if (allowed.length) toolArgs.push("--allowedTools", ...allowed.map(shq));
      // like "Bash(npm run test:*)" / "Read(~/**)" whose ( ) * ~ would break/inject the shell
      // command if pasted bare. (operator-self-injection only — guests can't reach TUI.)
      if (allowed.length) toolArgs.push("--allowedTools", ...allowed.map(shq));
    }
    if (process.env.CLAUDE_MCP_CONFIG) toolArgs.push("--mcp-config", shq(process.env.CLAUDE_MCP_CONFIG));
  } else {
    toolArgs = ["--strict-mcp-config", "--disallowedTools", shq("mcp__*")];
@@ -292,25 +367,29 @@ export async function runTuiTurn({
  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)
  // Env-token-only mode: the env token is set AND claude runs in an isolated home
  // (ehome !== rhome). In that case the scratch home must be CREDENTIAL-FREE (no
  // .credentials.json) so the env token — passed by buildTuiCmd — is the only credential
  // and is therefore authoritative (interactive claude otherwise PREFERS a credentials.json,
  // shadowing the env token; proven live on PI231). server.mjs derives TUI_HOME via
  // resolveTuiHome() so this isolated home is the DEFAULT once CLAUDE_CODE_OAUTH_TOKEN is set.
  const envTokenMode = !!process.env.CLAUDE_CODE_OAUTH_TOKEN && ehome !== rhome;
  // Ensure scratch cwd exists, then prepare the (scratch or real) HOME + trust the
  // cwd — before claude boots.
  if (!existsSync(cwd)) mkdirSync(cwd, { recursive: true });
-  prepareTuiHome(rhome, ehome, cwd);
+  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 });
-  // Build the env: disable marketplace auto-install, strip any Anthropic / CC
+  // Minimal env for spawnSync (tmux itself). The pane's claude env comes exclusively
-  // env vars that might interfere with interactive-mode classification.
+  // from the `env` prefix string built inside buildTuiCmd — tmux does NOT forward the
-  const env = { ...process.env, CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: "1" };
+  // spawning process's env to the pane, so the {env} here is intentionally minimal.
-  delete env.CLAUDECODE;
+  const env = { ...process.env };
-  delete env.ANTHROPIC_API_KEY;
+  env.HOME = ehome; // tmux needs HOME; all claude-specific vars go via buildTuiCmd prefix
  delete env.ANTHROPIC_BASE_URL;
  delete env.ANTHROPIC_AUTH_TOKEN;
  env.HOME = ehome; // claude reads credentials + writes the transcript under this HOME
  resolveTuiEntrypointEnv(env, entrypointMode);
  try {
    // 1. Boot the interactive session inside tmux, rooted at the scratch cwd.
@@ -9,24 +9,11 @@ import { readFileSync, existsSync, readdirSync } from "node:fs";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // Project-dir encoding: claude replaces every "/" AND every "." with "-".
 // Verified live (claude v2.1.158): cwd /home/u/.ocp-tui/work is stored under
 // projects/-home-u--ocp-tui-work/ (the "." in ".ocp-tui" becomes "-", yielding
 // the double dash). The earlier "/"-only rule was wrong for dotted paths; the
 // fixture cwd /tmp/tui-test happened to have no dots so it never surfaced.
 // NOTE: prefer findTranscriptPath() (glob by session-id) for resolution — it is
 // immune to the exact encoding rule. This helper is kept for the known-path case.
 export function encodeCwd(cwd) {
  return cwd.replace(/[/.]/g, "-");
 }
 export function transcriptPath(home, cwd, sessionId) {
  return `${home}/.claude/projects/${encodeCwd(cwd)}/${sessionId}.jsonl`;
 }
 // Locate a session's transcript by its UUID across every projects subdir, without
 // reconstructing the encoded cwd. Robust to whatever encoding claude applies.
 // Returns the path, or null if not present yet (it appears once the turn starts).
 // TODO: add a CI fixture-contract test (a captured real transcript) so schema drift
 //       in the claude JSONL format fails loudly rather than silently degrading.
 export function findTranscriptPath(home, sessionId) {
  if (!home || !sessionId) return null;
  const root = `${home}/.claude/projects`;
@@ -573,21 +573,42 @@ Usage:
  ocp restart            Restart the Claude proxy service
  ocp restart gateway    Restart the OpenClaw gateway
                         (briefly disconnects all Telegram/Discord bots)
 Note (macOS): restart does a full launchctl bootout + bootstrap, NOT
 `kickstart -k`. bootout+bootstrap re-reads the plist's EnvironmentVariables,
 so an env change you made (e.g. CLAUDE_BIND, CLAUDE_CODE_OAUTH_TOKEN) actually
 takes effect. `kickstart -k` only re-execs the process and reuses launchd's
 cached env, so env edits would be silently ignored. (Linux systemctl already
 re-reads its EnvironmentFile on restart.)
 EOF
 }
 # macOS only: reload a launchd agent via bootout + bootstrap so plist
 # EnvironmentVariables are re-read (kickstart -k would reuse the cached env).
 # Args: <uid> <label> <plist-path>. Returns 0 iff bootstrap succeeds.
 _launchd_reload() {
  local uid="$1" label="$2" plist="$3"
  [[ -f "$plist" ]] || return 1
  # bootout may legitimately fail if the agent is not currently loaded — that's fine,
  # we only require the subsequent bootstrap to succeed (the load that re-reads env).
  launchctl bootout "gui/$uid/$label" 2>/dev/null || true
  launchctl bootstrap "gui/$uid" "$plist" 2>/dev/null
 }
 cmd_restart() {
  if [[ "${1:-}" == "gateway" ]]; then
    echo "Restarting gateway..."
    openclaw gateway restart 2>&1
  else
    echo "Restarting proxy..."
-    # Try current service name, then legacy, then manual restart
+    # Try current service name, then legacy, then manual restart.
    # macOS: bootout+bootstrap (re-reads plist EnvironmentVariables — see cmd_restart_help).
    # Linux: systemctl --user restart already re-reads its EnvironmentFile.
    local uid
    uid=$(id -u)
-    if launchctl kickstart -k "gui/$uid/dev.ocp.proxy" 2>/dev/null; then
+    if _launchd_reload "$uid" "dev.ocp.proxy" "$HOME/Library/LaunchAgents/dev.ocp.proxy.plist"; then
      true
-    elif launchctl kickstart -k "gui/$uid/ai.openclaw.proxy" 2>/dev/null; then
+    elif _launchd_reload "$uid" "ai.openclaw.proxy" "$HOME/Library/LaunchAgents/ai.openclaw.proxy.plist"; then
      true
    elif systemctl --user restart ocp-proxy 2>/dev/null; then
      true
@@ -1,6 +1,6 @@
 {
  "name": "ocp",
-  "version": "3.12.0",
+  "version": "3.16.2",
  "description": "Slash commands for the OpenClaw Proxy",
  "main": "index.js",
  "type": "module",
@@ -9,6 +9,7 @@
  "openclaw": {
    "type": "plugin",
    "id": "ocp",
-    "pluginManifest": "openclaw.plugin.json"
+    "pluginManifest": "openclaw.plugin.json",
    "extensions": ["./index.js"]
  }
 }
@@ -1,6 +1,6 @@
 {
  "name": "open-claude-proxy",
-  "version": "3.20.0",
+  "version": "3.21.0",
  "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": {
@@ -20,7 +20,10 @@
 *   CLAUDE_MCP_CONFIG            — path to MCP server config JSON file
 *   CLAUDE_SESSION_TTL           — session TTL in ms (default: 3600000 = 1h)
 *   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_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)
 *   CLAUDE_BREAKER_COOLDOWN      — base ms to wait before retrying after circuit opens (default: 120000)
 *   CLAUDE_BREAKER_WINDOW        — sliding window duration in ms (default: 300000 = 5min)
@@ -31,16 +34,17 @@
 import { createServer } from "node:http";
 import { spawn, execFileSync } from "node:child_process";
 import { randomUUID, timingSafeEqual } from "node:crypto";
-import { readFileSync, readdirSync, accessSync, existsSync, constants, chmodSync, statSync } from "node:fs";
+import { readFileSync, readdirSync, accessSync, existsSync, constants, chmodSync, statSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 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 } from "./lib/tui/session.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 { 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"));
@@ -272,6 +276,15 @@ const SYSTEM_PROMPT = process.env.CLAUDE_SYSTEM_PROMPT || "";
 const MCP_CONFIG = process.env.CLAUDE_MCP_CONFIG || "";
 let SESSION_TTL = parseInt(process.env.CLAUDE_SESSION_TTL || "3600000", 10);
 let MAX_CONCURRENT = parseInt(process.env.CLAUDE_MAX_CONCURRENT || "8", 10);
 // FIX ⑥ (concurrency): bound on requests WAITING for a -p concurrency slot. Beyond
 // MAX_CONCURRENT, requests queue (up to CLAUDE_MAX_QUEUE) instead of being rejected; when the
 // queue is ALSO full, the request gets HTTP 429 + Retry-After (not an opaque 500). See
 // claudeSemaphore / acquireClaudeSlot below.
 const CLAUDE_MAX_QUEUE = parseInt(process.env.CLAUDE_MAX_QUEUE || "16", 10);
 // Retry-After seconds advertised on a 429 backpressure response. A claude turn is typically a
 // few seconds to tens of seconds; a small constant nudge keeps well-behaved clients from
 // hammering while the queue drains.
 const CLAUDE_QUEUE_RETRY_AFTER = parseInt(process.env.CLAUDE_QUEUE_RETRY_AFTER || "5", 10);
 const BREAKER_THRESHOLD = parseInt(process.env.CLAUDE_BREAKER_THRESHOLD || "6", 10);
 const BREAKER_COOLDOWN = parseInt(process.env.CLAUDE_BREAKER_COOLDOWN || "120000", 10);
 const BREAKER_WINDOW = parseInt(process.env.CLAUDE_BREAKER_WINDOW || "300000", 10);
@@ -279,6 +292,12 @@ const BREAKER_HALF_OPEN_MAX = parseInt(process.env.CLAUDE_BREAKER_HALF_OPEN_MAX
 const HEARTBEAT_INTERVAL = parseInt(process.env.CLAUDE_HEARTBEAT_INTERVAL || "0", 10);
 const BIND_ADDRESS = process.env.CLAUDE_BIND || "127.0.0.1";
 const NO_CONTEXT = process.env.CLAUDE_NO_CONTEXT === "true";
 // Kill-switch for the FIX-③ default-path spawn-home isolation (see resolveSpawnHome /
 // spawnHomeMode below). When "1", the -p/stream-json spawn always runs in the operator's
 // real HOME with no cwd override — byte-for-byte the pre-isolation behaviour — even if an
 // OAuth token is resolvable. Provided as an escape hatch in case a host depends on the real
 // HOME's claude config for the spawned process.
 const SPAWN_REAL_HOME = process.env.OCP_SPAWN_REAL_HOME === "1";
 const AUTH_MODE = process.env.CLAUDE_AUTH_MODE || (PROXY_API_KEY ? "shared" : "none");
 const ADMIN_KEY = process.env.OCP_ADMIN_KEY || "";
 const PROXY_ANONYMOUS_KEY = process.env.PROXY_ANONYMOUS_KEY || "";
@@ -300,7 +319,20 @@ let CACHE_TTL = parseInt(process.env.CLAUDE_CACHE_TTL || "0", 10); // 0 = disabl
 const TUI_MODE = process.env.CLAUDE_TUI_MODE === "true";
 const TUI_WALLCLOCK_MS = parseInt(process.env.CLAUDE_TUI_WALLCLOCK_MS || "120000", 10);
 const TUI_CWD  = process.env.OCP_TUI_CWD  || `${process.env.HOME}/.ocp-tui/work`;
-const TUI_HOME = process.env.OCP_TUI_HOME  || process.env.HOME;
+// HOME the interactive claude runs under. resolveTuiHome() decides:
 //   - OCP_TUI_HOME set            → that path (explicit override, back-compat).
 //   - else CLAUDE_CODE_OAUTH_TOKEN set → a CREDENTIAL-FREE scratch home
 //     (<HOME>/.ocp-tui/home) with NO .credentials.json, so the env token is the only
 //     credential and is authoritative — interactive claude otherwise PREFERS a
 //     credentials.json over the env var, so a stale one shadows the token (proven live on
 //     PI231) and a refresh on it can corrupt the single-use token. See ADR 0007 PR-D.
 //   - else (no env token)         → the operator's real home (legacy credentials.json path,
 //     byte-for-byte unchanged for hosts that intentionally rely on credentials.json).
 const TUI_HOME = resolveTuiHome({
  realHome:       process.env.HOME,
  configuredHome: process.env.OCP_TUI_HOME,
  envTokenSet:    !!process.env.CLAUDE_CODE_OAUTH_TOKEN,
 });
 const TUI_ENTRYPOINT = process.env.OCP_TUI_ENTRYPOINT || "cli"; // cli|auto|off — see ADR 0007
 // Independent concurrency bound for the TUI path (audit C-4). Default 2: a TUI turn is
 // HEAVY (per-request cold-boot of a tmux+claude session + up to TUI_WALLCLOCK_MS=120s of
@@ -319,6 +351,191 @@ const tuiStats = {
  entrypointMismatches: 0,   // count of cli-expected-but-got-other turns
 };
 // ── 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
 // project CLAUDE.md / skills) on EVERY request. Pure Anthropic API floor for haiku "hi" ≈ 1–2s;
 // the same claude CLI spawned in the operator's real HOME/cwd ≈ 10–28s; a clean minimal HOME +
 // CLAUDE_CODE_OAUTH_TOKEN ≈ 3–7s and authenticates fine. So the heavy global config is pure
 // per-request latency tax with no proxy benefit (a proxy must NOT leak the host's context into
 // the proxied turn — same rationale as NO_CONTEXT / the TUI path's CLAUDE_MDS suppression).
 //
 // FIX: when an OAuth token is resolvable, run the default spawn under a CREDENTIAL-FREE minimal
 // scratch HOME (`<realHome>/.ocp/spawn-home`) with cwd = that same neutral dir, and pass the
 // resolved token via CLAUDE_CODE_OAUTH_TOKEN so the env token is authoritative. This MIRRORS the
 // TUI path's resolveTuiHome() env-token mode (lib/tui/session.mjs): for `-p`, the env token wins
 // over a credentials.json (the opposite of interactive claude), so credential isolation is not
 // even strictly required for auth here, but a credential-FREE home is still the right shape —
 // nothing to refresh, nothing to corrupt, no heavy config to load.
 //
 // SAFETY: if NO token is resolvable → fall back to the real HOME with no cwd override (zero
 // regression). OCP_SPAWN_REAL_HOME=1 forces that legacy behaviour even when a token exists.
 // The scratch home holds NO .credentials.json / NO settings.json / NO plugins — it is created
 // minimal and (re)cleaned of any settings.json on prepare.
 const SPAWN_HOME_DIR = `${process.env.HOME}/.ocp/spawn-home`;
 // Idempotently prepare the minimal scratch HOME. Creates the dir if missing and removes any
 // settings.json that might have crept in, so the spawned claude loads no host settings/plugins.
 // Best-effort: a failure here degrades toward "dir may be missing", which spawn() tolerates by
 // erroring loudly — never a silent auth/credential corruption (there are no credentials here).
 function prepareSpawnHome(dir = SPAWN_HOME_DIR) {
  try {
    mkdirSync(`${dir}/.claude`, { recursive: true });
    // Belt-and-braces: ensure no settings.json/plugins leak in (this home is fully ours).
    for (const f of [`${dir}/.claude/settings.json`, `${dir}/.claude/settings.local.json`]) {
      try { if (existsSync(f)) rmSync(f, { force: true }); } catch { /* best effort */ }
    }
  } catch { /* best effort — spawn will surface a hard error if the dir is truly unusable */ }
 }
 // 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).
 //
 // 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 (SPAWN_REAL_HOME) {
    return { isolated: false, home: null, reason: "kill-switch (OCP_SPAWN_REAL_HOME=1)" };
  }
  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) {
    ensureSpawnHome(shm.home);
    return { isolated: true, home: shm.home, token, releaseFallback: null };
  }
  // 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 ──────────────
 // PROBLEM (proven): spawnClaudeProcess used `if (activeRequests >= MAX_CONCURRENT) throw` →
 // the client got an opaque 500 AND the rejection was NOT counted in stats (a 15-concurrent
 // stress run returned 7×500 while /health stats.errors stayed 0). The TUI path already has a
 // bounded-queue semaphore (TuiSemaphore); the -p path did not.
 //
 // FIX: requests beyond MAX_CONCURRENT WAIT on this semaphore (up to CLAUDE_MAX_QUEUE) instead of
 // being rejected. Only when the queue is ALSO full do we reject — with HTTP 429 + Retry-After
 // (deterministic backpressure), a distinct `concurrency_queue_full` log, and a stats.queueRejections
 // counter that shows up on /health. The slot is released on EVERY exit path via the existing
 // idempotent cleanup() (proc exit/close/error/timeout) — the #37/#40 slot-leak guard.
 const claudeSemaphore = new TuiSemaphore(MAX_CONCURRENT, { maxQueue: CLAUDE_MAX_QUEUE });
 // Tagged error so callers can map this single overflow case to HTTP 429 (every OTHER throw stays
 // a 500). Carries retryAfter for the Retry-After header.
 class ConcurrencyOverflowError extends Error {
  constructor(message) { super(message); this.name = "ConcurrencyOverflowError"; this.httpStatus = 429; this.retryAfter = CLAUDE_QUEUE_RETRY_AFTER; }
 }
 // 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
  try {
    await claudeSemaphore.acquire();
  } catch (e) {
    stats.queued = claudeSemaphore.queued;
    stats.queueRejections++;
    logEvent("warn", "concurrency_queue_full", {
      limit: claudeSemaphore.limit, maxQueue: claudeSemaphore.maxQueue,
      inflight: claudeSemaphore.inflight, queued: claudeSemaphore.queued,
    });
    throw new ConcurrencyOverflowError(
      `backpressure: concurrency limit (${claudeSemaphore.limit}) reached and wait queue ` +
      `(${claudeSemaphore.maxQueue}) is full — retry shortly`);
  }
  stats.queued = claudeSemaphore.queued;
  let released = false;
  return function releaseClaudeSlot() {
    if (released) return; // idempotent — cleanup() may be reached via multiple proc events
    released = true;
    claudeSemaphore.release();
    stats.queued = claudeSemaphore.queued;
  };
 }
 // SECURITY fail-loud: TUI-mode is incompatible with any configuration that allows
 // non-operator prompts to reach the interactive claude session. Three cases:
 //   1. AUTH_MODE=multi — guest/anonymous keys can submit prompts.
@@ -495,6 +712,28 @@ const cacheCleanupInterval = setInterval(() => {
  }
 }, 600000);
 // TUI defunct-session reap (periodic): the boot reap (below) only fires once, but a
 // long-lived host (PI231 ran 30 days without restart) accumulates defunct `<claude>`
 // zombies between restarts — the pane's claude is a child of the tmux server, not node,
 // so only the server can reap it (see reapStaleTuiSessions). We sweep every 15 min, but
 // ONLY when the TUI path is fully idle: reapStaleTuiSessions may `kill-server`, which would
 // tear down a live turn's pane, so we skip the sweep while any turn is inflight or queued.
 // RESIDUAL (documented, accepted): a brand-new request whose pane is created in the narrow
 // window between this idle-check and kill-server would have its pane torn down and fail the
 // turn cleanly via runTuiTurn's existing honesty gates (rare; the boot reap is the primary
 // 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.
 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" });
  } catch (e) { logEvent("error", "tui_periodic_reap_failed", { error: e.message }); }
 }, TUI_REAP_INTERVAL_MS) : null;
 if (tuiReapInterval && typeof tuiReapInterval.unref === "function") tuiReapInterval.unref();
 // ── Active child process tracking ────────────────────────────────────────
 const activeProcesses = new Set();
@@ -507,6 +746,8 @@ const stats = {
  sessionHits: 0,
  sessionMisses: 0,
  oneOffRequests: 0,
  queued: 0,           // current requests waiting for a -p concurrency slot (FIX ⑥)
  queueRejections: 0,  // total requests rejected with HTTP 429 because the wait-queue was full (FIX ⑥)
 };
 const recentErrors = []; // last 20 errors
@@ -734,11 +975,14 @@ function getModelTier(cliModel) {
 // (messagesToPrompt), so multi-turn correctness is preserved without sessions.
 // The sessions Map is retained for stats/logging but no longer drives --resume.
 // Reference: OLP ADR 0009 Amendment 1 + commit 97e7d16.
-function spawnClaudeProcess(model, messages, conversationId, keyName) {
+// FIX ⑥: concurrency is now bounded by the claudeSemaphore via acquireClaudeSlot(), which the
-  if (stats.activeRequests >= MAX_CONCURRENT) {
+// caller MUST await before calling this, passing the resulting release fn as `releaseSlot`. The
-    throw new Error(`concurrency limit reached (${stats.activeRequests}/${MAX_CONCURRENT})`);
+// old `if (activeRequests >= MAX_CONCURRENT) throw` gate (→ opaque 500, uncounted) is GONE: at
-  }
+// most MAX_CONCURRENT callers hold a slot when they reach here, so this spawn is always within
-
+// 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 = () => {}, spawnDecision = null) {
  const cliModel = MODEL_MAP[model] || model;
  // Circuit breaker: disabled (see comment at top of breaker section)
@@ -775,7 +1019,27 @@ function spawnClaudeProcess(model, messages, conversationId, keyName) {
    env.CLAUDE_CODE_DISABLE_AUTO_MEMORY = "1";
  }
-  const proc = spawn(CLAUDE, cliArgs, { env, stdio: ["pipe", "pipe", "pipe"] });
+  // 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 (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 = decision.home; // neutral cwd: no project CLAUDE.md/skills
  }
  const proc = spawn(CLAUDE, cliArgs, spawnOpts);
  activeProcesses.add(proc);
  const t0 = Date.now();
@@ -787,6 +1051,15 @@ function spawnClaudeProcess(model, messages, conversationId, keyName) {
    cleaned = true;
    clearTimeout(overallTimer);
    stats.activeRequests--;
    // FIX ⑥: free the concurrency slot for a queued waiter. releaseSlot is itself idempotent,
    // 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,
@@ -856,12 +1129,22 @@ function spawnClaudeProcess(model, messages, conversationId, keyName) {
 // 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.
-function callClaude(model, messages, conversationId, keyName) {
+async function callClaude(model, messages, conversationId, keyName) {
  // 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();
  return new Promise((resolve, reject) => {
    let ctx;
    try {
-      ctx = spawnClaudeProcess(model, messages, conversationId, keyName);
+      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);
    }
@@ -1028,14 +1311,32 @@ function startHeartbeat(res, intervalMs, sessionId) {
 // We parse line-by-line and forward content_block_delta text events as SSE.
 // The result event triggers the stop/[DONE] sequence.
 // Reference: OLP ADR 0009 Amendment 1 + commits 97e7d16, 65f945c.
-function callClaudeStreaming(model, messages, conversationId, res, authInfo = {}) {
+async function callClaudeStreaming(model, messages, conversationId, res, authInfo = {}) {
  const id = `chatcmpl-${randomUUID()}`;
  const created = Math.floor(Date.now() / 1000);
  // 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.
  let releaseSlot;
  try {
    releaseSlot = await acquireClaudeSlot();
  } catch (err) {
    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();
  let ctx;
  try {
-    ctx = spawnClaudeProcess(model, messages, conversationId, authInfo.keyName);
+    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" } });
  }
@@ -1228,12 +1529,23 @@ function sanitizeError(msg) {
 }
 // ── Response helpers ────────────────────────────────────────────────────
-function jsonResponse(res, status, data) {
+function jsonResponse(res, status, data, extraHeaders = null) {
  if (res.headersSent || res.writableEnded || res.destroyed) return;
-  res.writeHead(status, { "Content-Type": "application/json" });
+  // extraHeaders is optional + additive (e.g. Retry-After on a 429); Content-Type always wins.
  res.writeHead(status, { ...(extraHeaders || {}), "Content-Type": "application/json" });
  res.end(JSON.stringify(data));
 }
 // FIX ⑥: map an upstream error to the right HTTP response. A ConcurrencyOverflowError (the
 // wait-queue was full) becomes HTTP 429 + Retry-After + rate_limit_error; every other error
 // stays a 500 proxy_error (byte-for-byte the pre-fix behaviour for non-overflow errors).
 function respondUpstreamError(res, err) {
  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" } });
 }
 function sendSSE(res, data, hb) {
  hb?.reset();
  res.write(`data: ${JSON.stringify(data)}\n\n`);
@@ -1296,6 +1608,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) {
@@ -1309,17 +1666,8 @@ function getOAuthCredentials() {
    if (creds?.claudeAiOauth?.accessToken) return creds.claudeAiOauth;
  } catch { /* fall through to macOS keychain */ }
-  // 3. macOS keychain (both label formats)
+  // 3. macOS keychain (both label formats) — F5: label-memoized + 30s TTL cached (see above).
-  for (const label of ["claude-code-credentials", "Claude Code-credentials"]) {
+  return readKeychainCreds();
    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;
 }
 async function refreshOAuthToken(refreshToken) {
@@ -1653,7 +2001,9 @@ function applySettingUpdate(key, value) {
  switch (key) {
    case "timeout":          TIMEOUT = value; break;
-    case "maxConcurrent":    MAX_CONCURRENT = 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;
    case "sessionTTL":       SESSION_TTL = value; break;
    case "maxPromptChars":   MAX_PROMPT_CHARS = value; break;
    case "cacheTTL":         CACHE_TTL = value; break;
@@ -1862,7 +2212,7 @@ async function handleChatCompletions(req, res) {
        try { res.end(); } catch {}
        return;
      }
-      return jsonResponse(res, 500, { error: { message: sanitizeError(err.message), type: "proxy_error" } });
+      return respondUpstreamError(res, err);
    }
  }
@@ -1879,8 +2229,9 @@ async function handleChatCompletions(req, res) {
      try { res.end(); } catch {}
      return;
    }
-    // Sanitize error: strip internal file paths before sending to client
+    // Sanitize error: strip internal file paths before sending to client.
-    jsonResponse(res, 500, { error: { message: sanitizeError(err.message), type: "proxy_error" } });
+    // FIX ⑥: ConcurrencyOverflowError → 429 + Retry-After; all other errors → 500 (unchanged).
    respondUpstreamError(res, err);
  }
 }
@@ -2041,6 +2392,42 @@ const server = createServer(async (req, res) => {
      circuitBreaker: "disabled",
      sessions: sessionList,
      recentErrors: recentErrors.slice(-5),
      // ── FIX ③ spawn-home isolation surface — ADDITIVE (default -p/stream-json path) ──
      // Lets the operator confirm the latency-fix isolation is active without inspecting logs.
      // NEVER includes the token. mode: "isolated-scratch-home" | "real-home". home is the
      // scratch HOME path when isolated (null otherwise). For TUI_MODE the -p path is unused,
      // so report it as disabled.
      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: 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 ──
      // inflight/queued are live; queueRejections is cumulative (also in stats.queueRejections).
      // Lets the operator see backpressure instead of guessing from opaque 500s.
      concurrency: {
        maxConcurrent: MAX_CONCURRENT,
        maxQueue: claudeSemaphore.maxQueue,
        inflight: claudeSemaphore.inflight,
        queued: claudeSemaphore.queued,
        queueRejections: stats.queueRejections,
      },
      // ── TUI observability (audit C-5) — ADDITIVE block (ADR 0007 PR-B amendment) ──
      // /health is a grandfathered B.2 endpoint (ADR 0006). This block is NEW fields only;
      // every existing field above is byte-identical → behaviour-preserving for existing
@@ -2284,6 +2671,7 @@ function gracefulShutdown(signal) {
  clearInterval(sessionCleanupInterval);
  clearInterval(authCheckInterval);
  clearInterval(cacheCleanupInterval);
  if (tuiReapInterval) clearInterval(tuiReapInterval);
  closeDb();
  // 3. Kill all active child processes
@@ -2328,7 +2716,7 @@ server.listen(PORT, BIND_ADDRESS, () => {
  console.log(`Architecture: on-demand spawning (no pool)`);
  console.log(`Models: ${MODELS.map((m) => m.id).join(", ")}`);
  console.log(`Claude binary: ${CLAUDE}`);
-  console.log(`Timeout: ${TIMEOUT / 1000}s | Max concurrent: ${MAX_CONCURRENT}`);
+  console.log(`Timeout: ${TIMEOUT / 1000}s | Max concurrent: ${MAX_CONCURRENT} | Queue: ${CLAUDE_MAX_QUEUE} (429 on overflow)`);
  console.log(`Circuit breaker: disabled`);
  console.log(`Tools: ${SKIP_PERMISSIONS ? "all (skip-permissions)" : ALLOWED_TOOLS.join(", ")}`);
  console.log(`Sessions: TTL=${SESSION_TTL / 1000}s`);
@@ -2340,9 +2728,21 @@ server.listen(PORT, BIND_ADDRESS, () => {
  if (NO_CONTEXT) console.log(`Context: suppressed (CLAUDE_NO_CONTEXT=true — no CLAUDE.md, no auto-memory)`);
  if (CACHE_TTL > 0) console.log(`Cache: enabled (TTL=${CACHE_TTL / 1000}s)`);
  else console.log(`Cache: disabled (set CLAUDE_CACHE_TTL to enable)`);
  // FIX ③: announce default-path (-p/stream-json) spawn-home isolation mode (never logs the token).
  if (!TUI_MODE) {
    const shm = getSpawnHomeMode();
    if (shm.isolated) {
      console.log(`Spawn home: isolated-scratch-home (${shm.home}, cwd-neutral, env-token auth) — fast path`);
    } else {
      console.log(`Spawn home: real-home (${shm.reason}) — set CLAUDE_CODE_OAUTH_TOKEN for the isolated fast path`);
    }
  }
  if (TUI_MODE) {
    console.warn(`⚠️  TUI-mode ON — single-user only; do NOT enable on a multi-user OCP (guest prompts would run claude with operator filesystem access). See ADR 0007.`);
-    console.log(`  TUI-mode: ON home=${TUI_HOME} cwd=${TUI_CWD} wallclock=${TUI_WALLCLOCK_MS}ms maxConcurrent=${TUI_MAX_CONCURRENT}`);
+    const tuiAuth = process.env.CLAUDE_CODE_OAUTH_TOKEN
      ? (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}`);
    try {
      const n = reapStaleTuiSessions();
      if (n) logEvent("info", "tui_reaped_stale_sessions", { count: n });
@@ -5,6 +5,7 @@
 */
 import { getDb, createKey, listKeys, validateKey, recordUsage, checkQuota, updateKeyQuota, getKeyQuota, findKey, cacheHash, getCachedResponse, setCachedResponse, clearCache, getCacheStats, closeDb, hasCacheControl, singleflight, getInflightStats } from "./keys.mjs";
 import { isLoopbackBind } from "./lib/net.mjs";
 import { createSerialMutex, createTtlCache, isTokenExpiring, orderLabelsLastGoodFirst } from "./lib/spawn-auth.mjs";
 import { createHash } from "node:crypto";
 import { strict as assert } from "node:assert";
 import { unlinkSync } from "node:fs";
@@ -33,6 +34,17 @@ function test(name, fn) {
  }
 }
 async function testAsync(name, fn) {
  try {
    await fn();
    passed++;
    console.log(`  ✓ ${name}`);
  } catch (e) {
    failed++;
    console.log(`  ✗ ${name}: ${e.message}`);
  }
 }
 console.log("\n=== OCP Feature Tests (Quota + Cache) ===\n");
 // Initialize DB
@@ -1340,23 +1352,12 @@ test("streamStringAsSSE empty content: role + stop + [DONE] only", () => {
 });
 // ── Suite: TUI transcript reader ────────────────────────────────────────
-import { encodeCwd, transcriptPath, findTranscriptPath, parseTranscriptLines, isTerminalLine, extractLatestAssistantText, verifyEntrypoint, detectTuiUpstreamError } from "./lib/tui/transcript.mjs";
+import { findTranscriptPath, parseTranscriptLines, isTerminalLine, extractLatestAssistantText, verifyEntrypoint, detectTuiUpstreamError } from "./lib/tui/transcript.mjs";
 import { readFileSync as tuiReadFileSync, mkdtempSync as tuiMkdtemp0, mkdirSync as tuiMkdir0, writeFileSync as tuiWrite0 } from "node:fs";
 import { tmpdir as tuiTmp0 } from "node:os";
 console.log("\nTUI transcript — path formula:");
 test("encodeCwd replaces every slash AND every dot with dash", () => {
  // Verified live (claude v2.1.158): /home/u/.ocp-tui/work -> -home-u--ocp-tui-work
  assert.equal(encodeCwd("/home/u/.ocp-tui/work"), "-home-u--ocp-tui-work");
  assert.equal(encodeCwd("/tmp/tui-test"), "-tmp-tui-test"); // dot-free path still correct
 });
 test("transcriptPath composes HOME/.claude/projects/<enc>/<sid>.jsonl", () => {
  assert.equal(
    transcriptPath("/home/u", "/home/u/.ocp-tui/work", "abc-123"),
    "/home/u/.claude/projects/-home-u--ocp-tui-work/abc-123.jsonl"
  );
 });
 test("findTranscriptPath locates <sid>.jsonl across projects subdirs by UUID", () => {
  const home = tuiMkdtemp0(`${tuiTmp0()}/tui-home-`);
  const sid = "11111111-2222-3333-4444-555555555555";
@@ -1691,10 +1692,56 @@ test("buildTuiCmd keeps version pin + entrypoint label + MCP wall", () => {
  assert.ok(/-u CLAUDE_CODE_ENTRYPOINT/.test(auto), "auto mode unsets any inherited entrypoint");
 });
 // CLAUDE_CODE_OAUTH_TOKEN passthrough (PI231 401 incident): tmux doesn't forward the parent
 // env to the pane, so the token must be set explicitly on the pane command or the TUI claude
 // falls back to credentials.json (whose refresh token gets corrupted by the spawn/kill cycle).
 test("buildTuiCmd passes CLAUDE_CODE_OAUTH_TOKEN when the env is set (shq-escaped)", () => {
  const save = process.env.CLAUDE_CODE_OAUTH_TOKEN;
  try {
    process.env.CLAUDE_CODE_OAUTH_TOKEN = "sk-ant-oat01-abc123";
    const cmd = buildTuiCmd("/usr/bin/claude", "m", "sid-tok", "/home/u", "cli");
    // shq wraps in single quotes; a plain token renders as 'token'.
    assert.ok(cmd.includes("CLAUDE_CODE_OAUTH_TOKEN='sk-ant-oat01-abc123'"),
      "token must be set on the pane command, shq-escaped");
  } finally {
    if (save === undefined) delete process.env.CLAUDE_CODE_OAUTH_TOKEN;
    else process.env.CLAUDE_CODE_OAUTH_TOKEN = save;
  }
 });
 test("buildTuiCmd does NOT add CLAUDE_CODE_OAUTH_TOKEN when the env is unset", () => {
  const save = process.env.CLAUDE_CODE_OAUTH_TOKEN;
  try {
    delete process.env.CLAUDE_CODE_OAUTH_TOKEN;
    const cmd = buildTuiCmd("/usr/bin/claude", "m", "sid-notok", "/home/u", "cli");
    assert.ok(!/CLAUDE_CODE_OAUTH_TOKEN/.test(cmd),
      "no token added when env unset (credentials.json-only hosts unaffected)");
  } finally {
    if (save === undefined) delete process.env.CLAUDE_CODE_OAUTH_TOKEN;
    else process.env.CLAUDE_CODE_OAUTH_TOKEN = save;
  }
 });
 test("buildTuiCmd shq-escapes a token containing shell metacharacters (no injection)", () => {
  const save = process.env.CLAUDE_CODE_OAUTH_TOKEN;
  try {
    // A token with a single quote must be escaped via the '\'' idiom so it can't break out
    // of the shell string tmux runs via sh -c.
    process.env.CLAUDE_CODE_OAUTH_TOKEN = "tok'; rm -rf /;'";
    const cmd = buildTuiCmd("/usr/bin/claude", "m", "sid-inj", "/home/u", "cli");
    assert.ok(cmd.includes(`CLAUDE_CODE_OAUTH_TOKEN='tok'\\''; rm -rf /;'\\'''`),
      "single quote must be shq-escaped, not left bare");
    assert.ok(!/CLAUDE_CODE_OAUTH_TOKEN=tok'; rm/.test(cmd), "raw unescaped token must NOT appear");
  } finally {
    if (save === undefined) delete process.env.CLAUDE_CODE_OAUTH_TOKEN;
    else process.env.CLAUDE_CODE_OAUTH_TOKEN = save;
  }
 });
 test("buildTuiCmd OCP_TUI_FULL_TOOLS=1 grants -p-equivalent tool surface (single-user opt-in)", () => {
  const save = { ...process.env };
  const restore = () => {
-    for (const k of ["OCP_TUI_FULL_TOOLS", "CLAUDE_SKIP_PERMISSIONS", "CLAUDE_MCP_CONFIG", "CLAUDE_ALLOWED_TOOLS"]) {
+    for (const k of ["OCP_TUI_FULL_TOOLS", "CLAUDE_MCP_CONFIG", "CLAUDE_ALLOWED_TOOLS"]) {
      if (k in save) process.env[k] = save[k]; else delete process.env[k];
    }
  };
@@ -1706,20 +1753,14 @@ test("buildTuiCmd OCP_TUI_FULL_TOOLS=1 grants -p-equivalent tool surface (single
    // gate on: --allowedTools (default set incl Bash), MCP wall dropped
    process.env.OCP_TUI_FULL_TOOLS = "1";
    delete process.env.CLAUDE_SKIP_PERMISSIONS;
    delete process.env.CLAUDE_MCP_CONFIG;
    delete process.env.CLAUDE_ALLOWED_TOOLS;
    const full = buildTuiCmd("/usr/bin/claude", "m", "s", "/home/u", "cli");
    assert.ok(full.includes("--allowedTools") && full.includes("Bash"), "full-tools grants --allowedTools incl Bash");
    assert.ok(!full.includes("--strict-mcp-config") && !/--disallowedTools/.test(full), "full-tools drops the MCP wall");
-
+    assert.ok(!full.includes("--dangerously-skip-permissions"), "skip-permissions branch is removed (bricks headless TUI)");
    // skip-permissions supersedes --allowedTools
    process.env.CLAUDE_SKIP_PERMISSIONS = "true";
    const skip = buildTuiCmd("/usr/bin/claude", "m", "s", "/home/u", "cli");
    assert.ok(skip.includes("--dangerously-skip-permissions") && !skip.includes("--allowedTools"), "skip-permissions honored");
    // mcp-config threaded through
    delete process.env.CLAUDE_SKIP_PERMISSIONS;
    process.env.CLAUDE_MCP_CONFIG = "/tmp/mcp.json";
    const mcp = buildTuiCmd("/usr/bin/claude", "m", "s", "/home/u", "cli");
    assert.ok(/--mcp-config '\/tmp\/mcp.json'/.test(mcp), "mcp-config passed through (shq'd)");
@@ -1766,6 +1807,41 @@ test("reaper returns 0 for empty session list", () => {
  assert.equal(killed.length, 0);
 });
 // Defunct-zombie reaping (PI231 incident): the pane's claude is a child of the tmux server,
 // so only kill-server actually reaps it. We kill-server ONLY when no foreign session remains.
 console.log("\nTUI defunct-zombie reaping (kill-server):");
 test("reaper kill-servers when the server is ours-only (flush defunct claude zombies)", () => {
  const calls = [];
  const fakeTmux = (args) => {
    calls.push(args.join(" "));
    if (args[0] === "list-sessions") return { status: 0, stdout: "ocp-tui-aaaa\nocp-tui-bbbb\n" };
    return { status: 0, stdout: "" };
  };
  const n = reapStaleTuiSessions({ tmux: fakeTmux });
  assert.equal(n, 2, "killed both of our sessions");
  assert.ok(calls.includes("kill-server"), "kill-server fired — reaps the defunct backlog");
 });
 test("reaper does NOT kill-server when a foreign (non-ocp) session remains (coexistence)", () => {
  const calls = [];
  const fakeTmux = (args) => {
    calls.push(args.join(" "));
    if (args[0] === "list-sessions") return { status: 0, stdout: "ocp-tui-aaaa\nolp-tui-bbbb\n" };
    return { status: 0, stdout: "" };
  };
  const n = reapStaleTuiSessions({ tmux: fakeTmux });
  assert.equal(n, 1, "killed only our own session");
  assert.ok(!calls.includes("kill-server"), "kill-server MUST NOT fire — would disrupt olp-tui-*");
 });
 test("reaper does NOT kill-server when there is no server (status !== 0)", () => {
  const calls = [];
  const fakeTmux = (args) => { calls.push(args.join(" ")); return { status: 1, stdout: "" }; };
  reapStaleTuiSessions({ tmux: fakeTmux });
  assert.ok(!calls.includes("kill-server"), "no server → no kill-server (early return)");
 });
 // ── TUI home preparation (scratch vs real) ───────────────────────────────
 import { prepareTuiHome, ensureTuiCwdTrusted } from "./lib/tui/session.mjs";
 import { mkdtempSync as hMkdtemp, mkdirSync as hMkdir, writeFileSync as hWrite, readFileSync as hRead, existsSync as hExists, readlinkSync as hReadlink } from "node:fs";
@@ -1801,54 +1877,51 @@ test("prepareTuiHome real mode (tuiHome===realHome): no symlink, just trusts cwd
  assert.equal(j.projects[cwd].hasTrustDialogAccepted, true);         // cwd trusted in real config
 });
-// ── resolveTuiEntrypointEnv ───────────────────────────────────────────────
+// ── PR-D: env-token-only credential-isolated home (PI231 401 root fix) ──────
-import { resolveTuiEntrypointEnv } from "./lib/tui/session.mjs";
+// Interactive claude PREFERS ~/.claude/.credentials.json over CLAUDE_CODE_OAUTH_TOKEN, so a
-
+// stale/corrupt credentials.json SHADOWS the env token (proven live on PI231 — env token +
-console.log("\nresolveTuiEntrypointEnv:");
+// broken creds = 401; env token + creds moved aside = works). The fix runs the TUI claude in
-
+// a home with NO credentials.json so the env token is authoritative (and no refresh ever
-test("mode 'cli' sets CLAUDE_CODE_ENTRYPOINT=cli", () => {
+// happens → the single-use token can't be corrupted by the spawn+kill cycle).
-  const env = {};
+test("prepareTuiHome env-token mode: NO credentials.json (no symlink, no copy), .claude.json seeded", () => {
-  resolveTuiEntrypointEnv(env, "cli");
+  const realHome = hMkdtemp(`${hTmp()}/realT-`);
-  assert.equal(env.CLAUDE_CODE_ENTRYPOINT, "cli");
+  hMkdir(`${realHome}/.claude`, { recursive: true });
  hWrite(`${realHome}/.claude/.credentials.json`, '{"token":"real-oauth"}');  // real creds DO exist…
  hWrite(`${realHome}/.claude.json`, JSON.stringify({ theme: "dark", oauthAccount: { uuid: "secret" }, projects: { "/old/secret": { hasTrustDialogAccepted: true } } }));
  const tuiHome = hMkdtemp(`${hTmp()}/scratchT-`);
  const cwd = `${tuiHome}/work`;
  prepareTuiHome(realHome, tuiHome, cwd, { envTokenMode: true });
  // …but the scratch home has NO credentials file at all — neither symlink nor copy.
  assert.ok(!hExists(`${tuiHome}/.claude/.credentials.json`), "env-token home must have NO .credentials.json (the whole point — no shadowing, no refresh)");
  // .claude.json IS seeded: onboarding complete + ONLY the scratch cwd trusted (no dialog hang).
  const seed = JSON.parse(hRead(`${tuiHome}/.claude.json`, "utf8"));
  assert.equal(seed.hasCompletedOnboarding, true, "onboarding pre-completed → no onboarding dialog");
  assert.equal(seed.projects[cwd].hasTrustDialogAccepted, true, "scratch cwd pre-trusted → no trust dialog");
  // Minimal config: the credential-isolated home does NOT inherit the operator's account state.
  assert.equal(seed.theme, undefined, "env-token home is minimal — real config not copied in");
  assert.equal(seed.oauthAccount, undefined, "real account state not carried into the isolated home");
  assert.equal(seed.projects["/old/secret"], undefined, "operator project history not carried in");
  assert.ok(hExists(`${tuiHome}/.claude/projects`), "own projects/ dir for transcripts under the same home");
 });
-test("mode 'cli' overwrites an inherited CLAUDE_CODE_ENTRYPOINT value", () => {
+console.log("\nresolveTuiHome (env-token credential isolation, PR-D):");
-  const env = { CLAUDE_CODE_ENTRYPOINT: "sdk-cli" };
+import { resolveTuiHome, DEFAULT_TUI_SCRATCH_HOME } from "./lib/tui/session.mjs";
-  resolveTuiEntrypointEnv(env, "cli");
+
-  assert.equal(env.CLAUDE_CODE_ENTRYPOINT, "cli");
+test("resolveTuiHome: env token set + OCP_TUI_HOME unset → credential-free scratch home", () => {
  const h = resolveTuiHome({ realHome: "/home/u", configuredHome: undefined, envTokenSet: true });
  assert.equal(h, DEFAULT_TUI_SCRATCH_HOME("/home/u"));
  assert.equal(h, "/home/u/.ocp-tui/home");
  assert.notEqual(h, "/home/u", "must NOT be the real home — real home has the shadowing credentials.json");
 });
-test("mode 'auto' deletes CLAUDE_CODE_ENTRYPOINT (leaves unset)", () => {
+test("resolveTuiHome: env token UNSET → real home (legacy credentials.json path, unchanged)", () => {
-  const env = {};
+  const h = resolveTuiHome({ realHome: "/home/u", configuredHome: undefined, envTokenSet: false });
-  resolveTuiEntrypointEnv(env, "auto");
+  assert.equal(h, "/home/u", "no env token → real home, byte-for-byte the pre-fix behaviour");
  assert.equal(env.CLAUDE_CODE_ENTRYPOINT, undefined);
  assert.ok(!Object.prototype.hasOwnProperty.call(env, "CLAUDE_CODE_ENTRYPOINT"));
 });
-test("mode 'auto' deletes an inherited CLAUDE_CODE_ENTRYPOINT value", () => {
+test("resolveTuiHome: explicit OCP_TUI_HOME wins regardless of env token (back-compat)", () => {
-  const env = { CLAUDE_CODE_ENTRYPOINT: "sdk-cli" };
+  assert.equal(resolveTuiHome({ realHome: "/home/u", configuredHome: "/custom/home", envTokenSet: true }), "/custom/home");
-  resolveTuiEntrypointEnv(env, "auto");
+  assert.equal(resolveTuiHome({ realHome: "/home/u", configuredHome: "/custom/home", envTokenSet: false }), "/custom/home");
  assert.equal(env.CLAUDE_CODE_ENTRYPOINT, undefined);
  assert.ok(!Object.prototype.hasOwnProperty.call(env, "CLAUDE_CODE_ENTRYPOINT"));
 });
 test("mode 'off' leaves an inherited CLAUDE_CODE_ENTRYPOINT value untouched", () => {
  const env = { CLAUDE_CODE_ENTRYPOINT: "sdk-cli" };
  resolveTuiEntrypointEnv(env, "off");
  assert.equal(env.CLAUDE_CODE_ENTRYPOINT, "sdk-cli");
 });
 test("mode 'off' with no inherited value leaves env unchanged", () => {
  const env = { OTHER: "x" };
  resolveTuiEntrypointEnv(env, "off");
  assert.equal(env.CLAUDE_CODE_ENTRYPOINT, undefined);
  assert.equal(env.OTHER, "x");
 });
 test("default mode (no second arg) behaves like 'cli'", () => {
  const env = { CLAUDE_CODE_ENTRYPOINT: "sdk-cli" };
  resolveTuiEntrypointEnv(env);
  assert.equal(env.CLAUDE_CODE_ENTRYPOINT, "cli");
 });
 // ── TUI concurrency limiter + drift observability (PR-B: audit C-4 / C-5) ──
@@ -1918,6 +1991,45 @@ await asyncTest("wait queue is bounded — run() rejects with tui_queue_full whe
  assert.equal(sem.inflight, 0);
 });
 console.log("\n-p concurrency wait-queue (FIX ⑥ — same TuiSemaphore reused for the -p path):");
 // server.mjs reuses TuiSemaphore as `claudeSemaphore = new TuiSemaphore(MAX_CONCURRENT,
 // { maxQueue: CLAUDE_MAX_QUEUE })` and wraps acquire()/release() in acquireClaudeSlot(). These
 // tests assert the contract that the 429-mapping depends on: requests beyond the limit QUEUE
 // (not reject), only an overflow past the queue rejects (→ HTTP 429 in server.mjs), and a
 // released slot is reusable (the #37/#40 slot-leak guard — no leak on normal completion).
 await asyncTest("FIX ⑥: requests beyond MAX_CONCURRENT queue, not reject (limit=1, queue=1)", async () => {
  const sem = new TuiSemaphore(1, { maxQueue: 1 });   // mirrors CLAUDE_MAX_CONCURRENT=1, CLAUDE_MAX_QUEUE=1
  const g1 = deferred();
  const inflightP = sem.run(async () => { await g1.p; });   // request 1 — holds the only slot
  await new Promise((r) => setImmediate(r));
  assert.equal(sem.inflight, 1, "req1 inflight");
  const queuedP = sem.run(async () => {});                  // request 2 — WAITS (queued), does NOT reject
  await new Promise((r) => setImmediate(r));
  assert.equal(sem.queued, 1, "req2 queued (waits), not rejected → would be served, not 429");
  // request 3 — queue full → reject (server.mjs maps this single case to 429 + Retry-After)
  await assert.rejects(sem.run(async () => {}), /tui_queue_full|queue/, "req3 overflows → reject (→429)");
  g1.resolve();
  await inflightP; await queuedP;
  assert.equal(sem.inflight, 0, "all slots released after drain (no leak)");
  assert.equal(sem.queued, 0, "queue fully drained");
 });
 await asyncTest("FIX ⑥: slot released on normal completion is immediately reusable (no #37/#40 leak)", async () => {
  const sem = new TuiSemaphore(1, { maxQueue: 16 });   // mirrors default CLAUDE_MAX_QUEUE=16
  for (let i = 0; i < 5; i++) {
    await sem.run(async () => { /* a normal, completing turn */ });
    assert.equal(sem.inflight, 0, `slot released after turn ${i}`);
  }
  // Prove the limit still binds after many acquire/release cycles.
  const g = deferred();
  const held = sem.run(async () => { await g.p; });
  await new Promise((r) => setImmediate(r));
  assert.equal(sem.inflight, 1, "limit still enforced after reuse cycles");
  g.resolve(); await held;
  assert.equal(sem.inflight, 0);
 });
 console.log("\nTUI drift observability (C-5):");
 test("recordTuiEntrypoint: observed 'cli' is NOT a mismatch and sets lastEntrypoint", () => {
@@ -2298,8 +2410,131 @@ test("isLoopbackBind: '100.64.0.1' → false (Tailscale IP)", () => {
  assert.equal(isLoopbackBind("100.64.0.1"), false);
 });
-// ── Cleanup ──
+// ── Spawn-auth primitives (F3 / F5 / F6, lib/spawn-auth.mjs) ──
-closeDb();
+// Pure, dependency-injected primitives extracted from server.mjs so the spawn-token concurrency /
 // caching / expiry logic is testable without booting the server or mocking execFileSync/spawn.
 console.log("\nSpawn-auth (F3 mutex / F5 TTL cache + label memo / F6 expiry gate):");
-console.log(`\n=== Results: ${passed} passed, ${failed} failed ===\n`);
+// F5: expiry gate — the load-bearing invariant that lets a short-TTL keychain cache stay safe.
-process.exit(failed > 0 ? 1 : 0);
+test("isTokenExpiring: creds within 5-min buffer → true", () => {
  assert.equal(isTokenExpiring({ expiresAt: 1000 }, 1000 - 300000, 300000), true); // exactly at buffer edge
  assert.equal(isTokenExpiring({ expiresAt: 1000 }, 900, 300000), true);           // past the edge
 });
 test("isTokenExpiring: creds well beyond buffer → false", () => {
  assert.equal(isTokenExpiring({ expiresAt: 10_000_000 }, 0, 300000), false);
 });
 test("isTokenExpiring: no expiresAt (long-lived env token) → never expiring", () => {
  assert.equal(isTokenExpiring({ accessToken: "x" }, Date.now(), 300000), false);
  assert.equal(isTokenExpiring(null, Date.now(), 300000), false);
 });
 // F5: last-good label ordering — one exec instead of two on the steady-state keychain path.
 test("orderLabelsLastGoodFirst: last-good label is tried first", () => {
  const labels = ["A", "B"];
  assert.deepEqual(orderLabelsLastGoodFirst(labels, "B"), ["B", "A"]);
 });
 test("orderLabelsLastGoodFirst: null/unknown last-good → original order, fresh array", () => {
  const labels = ["A", "B"];
  assert.deepEqual(orderLabelsLastGoodFirst(labels, null), ["A", "B"]);
  assert.deepEqual(orderLabelsLastGoodFirst(labels, "Z"), ["A", "B"]);
  assert.notEqual(orderLabelsLastGoodFirst(labels, null), labels); // does not mutate/alias input
 });
 // F5: TTL cache — bounds how often we RE-READ the keychain (not how often we re-decide expiry).
 test("createTtlCache: serves cached value within TTL, re-produces after TTL", () => {
  const cache = createTtlCache({ ttlMs: 30000 });
  let calls = 0;
  const produce = () => { calls++; return `v${calls}`; };
  assert.equal(cache.get(produce, 0), "v1");
  assert.equal(cache.get(produce, 10000), "v1"); // within TTL → cached, producer NOT called
  assert.equal(calls, 1);
  assert.equal(cache.get(produce, 40000), "v2"); // past TTL → re-produced
  assert.equal(calls, 2);
 });
 test("createTtlCache: caches a null miss (absent source not re-probed within TTL)", () => {
  const cache = createTtlCache({ ttlMs: 30000 });
  let calls = 0;
  const produce = () => { calls++; return null; };
  assert.equal(cache.get(produce, 0), null);
  assert.equal(cache.get(produce, 5000), null);
  assert.equal(calls, 1); // the null was cached, not re-probed
 });
 // F5 core safety property: a short-TTL cache CANNOT reintroduce the #146 forever-stale bug because
 // the expiry gate is applied to the CACHED creds on every use. The cache keeps returning the same
 // creds object, but isTokenExpiring flips to true the moment the clock crosses the expiry buffer.
 test("TTL cache respects expiry gate: cached creds still rejected once clock passes expiry", () => {
  const cache = createTtlCache({ ttlMs: 30000 });
  const creds = { accessToken: "tok", expiresAt: 1_000_000 };
  // t=980_000: cached AND not yet within the 5-min (300_000) buffer → usable.
  const c1 = cache.get(() => creds, 980_000 - 300_000 - 1);
  assert.equal(isTokenExpiring(c1, 980_000 - 300_000 - 1, 300000), false);
  // t=800_000 later: SAME cached object returned (within TTL of the second read window), but now
  // within the expiry buffer → gate rejects it → caller falls back to real HOME. No forever-stale.
  const c2 = cache.get(() => creds, 990_000);
  assert.equal(c2, c1, "cache returns the same creds object");
  assert.equal(isTokenExpiring(c2, 990_000, 300000), true, "expiry gate still fires on cached creds");
 });
 // ── Async: F3 real-HOME fallback serialization mutex ──
 async function runAsyncTests() {
  await testAsync("createSerialMutex: second waiter blocks until first holder releases", async () => {
    const mutex = createSerialMutex();
    const order = [];
    const rel1 = await mutex.acquire();
    order.push("h1-enter");
    let secondEntered = false;
    const p2 = mutex.acquire().then((rel2) => { secondEntered = true; order.push("h2-enter"); return rel2; });
    await new Promise((r) => setTimeout(r, 15));
    assert.equal(secondEntered, false, "second waiter must NOT enter while first holds the mutex");
    order.push("h1-release");
    rel1();
    const rel2 = await p2;
    assert.equal(secondEntered, true, "second waiter enters only after release");
    rel2();
    assert.deepEqual(order, ["h1-enter", "h1-release", "h2-enter"]);
  });
  await testAsync("createSerialMutex: N acquires run strictly in FIFO order, never overlapping", async () => {
    const mutex = createSerialMutex();
    const events = [];
    let active = 0;
    async function critical(id) {
      const rel = await mutex.acquire();
      active++;
      assert.equal(active, 1, `only one holder at a time (id=${id})`);
      events.push(`start${id}`);
      await new Promise((r) => setTimeout(r, 5));
      events.push(`end${id}`);
      active--;
      rel();
    }
    await Promise.all([critical(1), critical(2), critical(3)]);
    assert.deepEqual(events, ["start1", "end1", "start2", "end2", "start3", "end3"]);
  });
  await testAsync("createSerialMutex: release() is idempotent (double-release does not double-admit)", async () => {
    const mutex = createSerialMutex();
    const rel1 = await mutex.acquire();
    rel1();
    rel1(); // second call must be a no-op
    const rel2 = await mutex.acquire(); // should acquire cleanly, exactly once
    let thirdEntered = false;
    const p3 = mutex.acquire().then((r) => { thirdEntered = true; return r; });
    await new Promise((r) => setTimeout(r, 15));
    assert.equal(thirdEntered, false, "double-release must not have leaked an extra admit slot");
    rel2();
    (await p3)();
  });
 }
 // ── Cleanup ──
 runAsyncTests().then(() => {
  closeDb();
  console.log(`\n=== Results: ${passed} passed, ${failed} failed ===\n`);
  process.exit(failed > 0 ? 1 : 0);
 }).catch((e) => {
  console.error("async test runner crashed:", e);
  closeDb();
  process.exit(1);
 });