fix(tui): scope session prefix + reap/kill-server to this instance's port (F7)

Audit finding F7 (LOW): lib/tui/session.mjs hardcoded SESSION_PREFIX = "ocp-tui-" as a bare, host-wide constant. The boot-reap and periodic idle-reap in server.mjs used it to decide which tmux sessions to kill-session and whether to kill-server (which flushes defunct <claude> zombies but tears down the WHOLE tmux server, including any live pane). The coexistence guard only ever spared foreign product prefixes (olp-tui-*); a SECOND OCP instance on the same host — e.g. a temporary verification instance stood up alongside production, a real pattern used during PR #144/#146 verification — was indistinguishable from "ours" and could have its LIVE sessions reaped/kill-server'd by the other instance's boot or periodic sweep. Fix: scope the session-name prefix to this instance's own listen port (the natural stable per-instance discriminator on one host — two OCP instances cannot share a port): `ocp-tui-<port>-`. A sibling instance's `ocp-tui-<otherPort>-*` sessions now fail the own-prefix startsWith check and fall into the same "othersRemain" bucket as olp-tui-*, so they are never touched and never used to justify kill-server. lib/tui/session.mjs: - sessionPrefixForPort(port) replaces the bare SESSION_PREFIX export. - reapStaleTuiSessions({ tmux, port, includeLegacy }) now requires port and computes its own prefix from it. - runTuiTurn({ ..., port }) builds the tmux session name from sessionPrefixForPort(port) instead of the old bare constant. - LEGACY_SESSION_PREFIX / LEGACY_SESSION_NAME_RE (exact "ocp-tui-<8-hex>" shape, no port segment) describe the OLD pre-fix session-name shape, retained only for the migration below. Legacy migration rule (chosen + reasoning): a bare-prefix legacy session cannot be created by any post-fix OCP process, so if one is seen it is presumed to be an orphaned zombie from THIS instance's own PRE-fix process generation (left behind across an in-place upgrade), not a stranger's. reapStaleTuiSessions() therefore accepts an includeLegacy flag: server.mjs's one-time BOOT reap passes includeLegacy: true (claims exact-legacy-shape sessions as its own, enabling cleanup right after an upgrade); the periodic 15-min idle sweep does NOT set it, so a lingering legacy-shaped session during steady-state is conservatively treated as foreign and cannot trigger kill-server on a routine tick. Residual (documented, accepted): a genuinely-still-running PRE-fix OCP instance coexisting on the host at the exact moment a new instance boots could have its live legacy session reaped — the same class of residual risk the audit finding itself accepts ("no live instance of the new version creates them"); this PR does not regress that scenario, it only removes the far more common same-version collision that is the actual F7 finding. LEGACY_SESSION_NAME_RE (`^ocp-tui-[0-9a-f]{8}$`) can never match the new shape: the new shape always inserts a literal "-" between the port digits and the 8-hex suffix, which the anchored 8-hex-only legacy regex cannot satisfy. server.mjs changes are local TUI session-lifecycle infrastructure (tmux session naming, boot/periodic reap, kill-server) with no cli.js wire analogue — verified via `strings` against the compiled claude CLI 2.1.198 binary (this machine ships cli.js as a Mach-O binary per ALIGNMENT.md's "OAuth token-host verification" precedent): cli.js contains only `env.TMUX` detection (whether IT is running inside a tmux pane) and an unrelated `--remote-control-session-name-prefix` flag for its own remote-control feature — no session-prefix/reap/ kill-server mechanism of any kind. Per ALIGNMENT.md Rule 2, this is declared absent: no endpoint, header, request, or response shape changed; only OCP's own local process-lifecycle bookkeeping. No PORT literal was hardcoded (CI port-SPOT check) — PORT is threaded through from the existing server.mjs SPOT (lib/constants.mjs DEFAULT_PORT via CLAUDE_PROXY_PORT). test-features.mjs: rewrote the reaper suite's fixture session names to the new port-scoped shape, added tests for sessionPrefixForPort(), LEGACY_SESSION_NAME_RE's non-collision with the new shape, a sibling same-host OCP instance being treated as foreign (F7 regression test), and the includeLegacy boot-migration behavior (claims legacy zombies, still spares a sibling instance's port-scoped session). Verified: node --check server.mjs && node --check lib/tui/session.mjs && npm test → 243 passed, 0 failed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
fix(server): re-resolve -p spawn OAuth token per-spawn, expiry-aware (③ regression) (#146 )
2026-07-22 05:25:08 +00:00 · 2026-07-07 22:37:58 +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 · 2026-06-13 17:04:07 +10:00
10 changed files with 698 additions and 186 deletions
@@ -1,5 +1,29 @@
 # 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))
@@ -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
-devices on the network can share my Claude Pro/Max subscription.
+I want to install OCP on this device as a LAN server so my own devices on the
+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:
@@ -901,7 +935,9 @@ See [Subscription-pool (TUI) mode](#subscription-pool-tui-mode) and ADR 0007 PR-
 | `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 |
@@ -913,13 +949,14 @@ See [Subscription-pool (TUI) mode](#subscription-pool-tui-mode) and ADR 0007 PR-
 | `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` | *(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

@@ -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.*
@@ -15,14 +15,48 @@ import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { readTuiTranscript } from "./transcript.mjs";

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

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

-// Kill ONLY our own stale sessions. Scoped to SESSION_PREFIX so a co-hosted
-// OLP test instance's `olp-tui-*` sessions are never touched.
+// Kill ONLY our own stale sessions. Scoped to sessionPrefixForPort(port) so a co-hosted
+// OLP test instance's `olp-tui-*` sessions — AND a co-hosted second OCP instance's
+// `ocp-tui-<otherPort>-*` sessions — are never touched (F7 fix).
 //
 // Defunct-reaping (PI231 incident): the pane's `claude` process is a child of the
 // long-lived tmux SERVER daemon, NOT of the OCP node process — `tmux new-session -d`
@@ -36,23 +70,40 @@ const defaultTmux = (args, opts = {}) =>
 // merely re-signalling — is to stop the tmux server: when the server exits, the kernel
 // reparents its surviving children to init (PID 1), which reaps them immediately.
 //
-// So after killing our own sessions, if the server has NO sessions left of ANY prefix
-// (i.e. nothing we could disrupt — no co-hosted `olp-tui-*` or other instance), we
-// `kill-server` to flush the defunct backlog. If ANY non-ocp session remains we leave the
-// server running (coexistence rule, ADR 0007) and let the next boot/periodic sweep retry
-// once the server is otherwise idle.
-export function reapStaleTuiSessions({ tmux = defaultTmux } = {}) {
+// `port` (required) is this instance's own listen port (server.mjs's PORT / lib/constants.mjs
+// DEFAULT_PORT resolution) — the SPOT for "which sessions are ours."
+//
+// `includeLegacy` (default false): when true, sessions matching the exact OLD bare-prefix
+// shape (LEGACY_SESSION_NAME_RE) are ALSO treated as ours for kill-session purposes. This is
+// the boot-time legacy migration: an operator upgrading past this fix could otherwise be left
+// with orphaned bare-prefix zombie sessions from the PREVIOUS (pre-fix) process generation of
+// this SAME instance, since no live instance of the new version ever creates that shape again
+// — a legacy-shaped session found at boot is therefore presumed to be this instance's own
+// leftover, not a stranger's. Passed true ONLY from the one-time boot-reap call site in
+// server.mjs; the periodic idle-reap sweep does NOT set it, so a lingering legacy session
+// during steady-state is conservatively treated as foreign (correctly blocking kill-server)
+// rather than assumed to be ours on every 15-minute tick. Residual (accepted, documented):
+// if a genuinely-still-running PRE-FIX OCP instance is coexisting on the same host at the
+// exact moment a new instance boots, its live legacy-shaped session could be reaped — the
+// same class of residual risk the audit finding itself accepts ("no live instance of the new
+// version creates them"); this PR does not regress that scenario, it only removes the far
+// more common same-version collision (the actual F7 finding).
+export function reapStaleTuiSessions({ tmux = defaultTmux, port, includeLegacy = false } = {}) {
  const r = tmux(["list-sessions", "-F", "#{session_name}"]);
  if (!r || r.status !== 0) return 0; // no tmux server / no sessions
  const names = String(r.stdout || "").split("\n").map((s) => s.trim()).filter(Boolean);
+  const ownPrefix = sessionPrefixForPort(port);
  let killed = 0;
  let othersRemain = false;
  for (const name of names) {
-    if (name.startsWith(SESSION_PREFIX)) {
+    const isOwn = name.startsWith(ownPrefix);
+    const isLegacyOwn = includeLegacy && LEGACY_SESSION_NAME_RE.test(name);
+    if (isOwn || isLegacyOwn) {
      tmux(["kill-session", "-t", name]);
      killed++;
    } else {
-      othersRemain = true; // a session we do NOT own (e.g. olp-tui-*) — never kill-server
+      othersRemain = true; // a session we do NOT own (olp-tui-*, a sibling ocp-tui-<otherPort>-*,
+                            // or — outside includeLegacy — a legacy-shaped name) — never kill-server
    }
  }
  // Reap defunct `claude` zombies: safe ONLY when the server is now ours-only/empty.
@@ -244,23 +295,6 @@ export function prepareTuiHome(realHome, tuiHome, cwd, { envTokenMode = false }
  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),
@@ -321,27 +355,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
-  //     SINGLE-USER / trusted TUI deployment can run a tool-using agent (e.g. an OpenClaw
-  //     assistant that needs Bash/Read/Write/MCP) on the subscription pool. This mirrors
-  //     buildCliArgs() in server.mjs. Safe to gate ON only because TUI is hard-incompatible
-  //     with AUTH_MODE=multi (server.mjs refuses to boot), so it can never widen a guest's
-  //     surface. Env mirrors server.mjs's CLAUDE_ALLOWED_TOOLS / _SKIP_PERMISSIONS / _MCP_CONFIG.
+  //     (--allowedTools [+ --mcp-config]), so a SINGLE-USER / trusted TUI deployment can
+  //     run a tool-using agent (e.g. an OpenClaw assistant that needs Bash/Read/Write/MCP)
+  //     on the subscription pool. ALWAYS uses --allowedTools (CLAUDE_SKIP_PERMISSIONS /
+  //     --dangerously-skip-permissions is intentionally removed: claude v2.1.x shows an
+  //     interactive bypass-acceptance screen in headless tmux that nothing can answer →
+  //     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") {
-      toolArgs.push("--dangerously-skip-permissions");
-    } else {
-      const allowed = (process.env.CLAUDE_ALLOWED_TOOLS ||
-        "Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch,Agent")
-        .split(",").map((s) => s.trim()).filter(Boolean);
-      // shq EACH token: buildTuiCmd returns a SHELL STRING (run by tmux via sh -c), unlike
-      // buildCliArgs which returns an argv array to spawn(). claude accepts scoped specifiers
-      // 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));
-    }
+    const allowed = (process.env.CLAUDE_ALLOWED_TOOLS ||
+      "Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch,Agent")
+      .split(",").map((s) => s.trim()).filter(Boolean);
+    // shq EACH token: buildTuiCmd returns a SHELL STRING (run by tmux via sh -c), unlike
+    // buildCliArgs which returns an argv array to spawn(). claude accepts scoped specifiers
+    // 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__*")];
@@ -378,12 +409,15 @@ export async function runTuiTurn({
  home,
  realHome,
  cwd,
+  port,
  wallclockMs = 120000,
  entrypointMode = "cli",
  tmux = defaultTmux,
 }) {
  const sessionId = randomUUID();
-  const tmuxName  = SESSION_PREFIX + sessionId.slice(0, 8);
+  // Port-scoped session name (F7 fix) — see sessionPrefixForPort / reapStaleTuiSessions
+  // for why this instance's own listen port is the namespace discriminator.
+  const tmuxName  = sessionPrefixForPort(port) + sessionId.slice(0, 8);
  const ehome     = home || process.env.HOME;       // HOME claude runs under (scratch or real)
  const rhome     = realHome || process.env.HOME;   // real home (OAuth + onboarded config source)

@@ -405,15 +439,11 @@ export async function runTuiTurn({
  const promptFile = `${tmpDir}/prompt.txt`;
  writeFileSync(promptFile, prompt, { mode: 0o600 });

-  // Build the env: disable marketplace auto-install, strip any Anthropic / CC
-  // env vars that might interfere with interactive-mode classification.
-  const env = { ...process.env, CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: "1" };
-  delete env.CLAUDECODE;
-  delete env.ANTHROPIC_API_KEY;
-  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);
+  // Minimal env for spawnSync (tmux itself). The pane's claude env comes exclusively
+  // from the `env` prefix string built inside buildTuiCmd — tmux does NOT forward the
+  // spawning process's env to the pane, so the {env} here is intentionally minimal.
+  const env = { ...process.env };
+  env.HOME = ehome; // tmux needs HOME; all claude-specific vars go via buildTuiCmd prefix

  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.1",
+  "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,7 +34,7 @@
 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";
@@ -272,6 +275,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 +291,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 || "";
@@ -332,6 +350,135 @@ 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 ONCE, lazily + memoized (so it runs after
+// getOAuthCredentials is defined regardless of source order, and the token probe happens at most
+// once). Returns { isolated, home, token } where:
+//   - 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).
+// Caches only the isolation DECISION (isolated/home/reason), NOT the token — the token 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), so a startup snapshot 401s once it expires (caused a ~31h Mac-mini 401 outage,
+// 2026-06-26). 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).
+let _spawnHomeMode = null;
+function getSpawnHomeMode() {
+  if (_spawnHomeMode) return _spawnHomeMode;
+  if (SPAWN_REAL_HOME) {
+    _spawnHomeMode = { isolated: false, home: null, reason: "kill-switch (OCP_SPAWN_REAL_HOME=1)" };
+    return _spawnHomeMode;
+  }
+  let hasToken = false;
+  try { hasToken = !!(getOAuthCredentials()?.accessToken); } catch { hasToken = false; }
+  if (hasToken) {
+    prepareSpawnHome(SPAWN_HOME_DIR);
+    _spawnHomeMode = { isolated: true, home: SPAWN_HOME_DIR, reason: "oauth token resolved" };
+  } else {
+    _spawnHomeMode = { isolated: false, home: null, reason: "no oauth token resolvable" };
+  }
+  return _spawnHomeMode;
+}
+
+// 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 has passed (5-min buffer): 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 (creds.expiresAt && Date.now() + 300000 >= creds.expiresAt) return null;
+    return creds.accessToken;
+  } catch { return null; }
+}
+
+// ── 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.
@@ -524,7 +671,13 @@ 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();
+    // F7 fix: scope to THIS instance's own port; a sibling ocp-tui-<otherPort>-* session
+    // (a second OCP instance on the same host) is treated as foreign, same as olp-tui-*.
+    // includeLegacy is NOT set here — see reapStaleTuiSessions' comment: the periodic sweep
+    // conservatively treats any lingering bare-prefix legacy session as foreign so it can
+    // never trigger kill-server on a steady-state tick; only the one-time boot reap below
+    // claims legacy-shaped zombies.
+    const n = reapStaleTuiSessions({ port: PORT });
    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;
@@ -542,6 +695,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

@@ -769,11 +924,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) {
-  if (stats.activeRequests >= MAX_CONCURRENT) {
-    throw new Error(`concurrency limit reached (${stats.activeRequests}/${MAX_CONCURRENT})`);
-  }
-
+// FIX ⑥: concurrency is now bounded by the claudeSemaphore via acquireClaudeSlot(), which the
+// caller MUST await before calling this, passing the resulting release fn as `releaseSlot`. The
+// 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 = () => {}) {
  const cliModel = MODEL_MAP[model] || model;

  // Circuit breaker: disabled (see comment at top of breaker section)
@@ -810,7 +968,31 @@ 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): default-path spawn-home isolation. When a token is resolvable (and the
+  // OCP_SPAWN_REAL_HOME kill-switch is off), run claude under a credential-free minimal HOME
+  // with cwd = that same neutral dir, so it loads NONE of the operator's global ~/.claude
+  // (plugins/skills/hooks) or the ~/ocp project CLAUDE.md/skills — the measured 10–28s → 3–7s
+  // latency win. The env token is authoritative for `-p` (unlike interactive claude). When no
+  // token is resolvable, falls back to real HOME + inherited cwd (zero regression). See
+  // getSpawnHomeMode() / prepareSpawnHome() above. The DISABLE_CLAUDE_MDS / AUTO_MEMORY flags
+  // are set unconditionally in isolated mode (belt-and-braces; mirrors the TUI path).
+  const spawnHome = getSpawnHomeMode();
+  const spawnOpts = { env, stdio: ["pipe", "pipe", "pipe"] };
+  if (spawnHome.isolated) {
+    // Re-resolve the token FRESH per spawn (never a startup snapshot — keychain tokens rotate;
+    // a stale snapshot 401s). If unresolvable right now, fall through to real HOME so the spawned
+    // claude resolves + refreshes credentials natively instead of 401ing on a stale/null token.
+    const freshToken = resolveSpawnToken();
+    if (freshToken) {
+      env.HOME = spawnHome.home;
+      env.CLAUDE_CODE_OAUTH_TOKEN = freshToken; // env token is authoritative for -p
+      env.CLAUDE_CODE_DISABLE_CLAUDE_MDS = "1";
+      env.CLAUDE_CODE_DISABLE_AUTO_MEMORY = "1";
+      spawnOpts.cwd = spawnHome.home; // neutral cwd: no project CLAUDE.md/skills
+    }
+  }
+
+  const proc = spawn(CLAUDE, cliArgs, spawnOpts);
  activeProcesses.add(proc);

  const t0 = Date.now();
@@ -822,6 +1004,10 @@ 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 */ }
  }

  // Guarantee slot release on ANY exit path (normal close, error, timeout kill,
@@ -891,12 +1077,18 @@ 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();
  return new Promise((resolve, reject) => {
    let ctx;
    try {
-      ctx = spawnClaudeProcess(model, messages, conversationId, keyName);
+      ctx = spawnClaudeProcess(model, messages, conversationId, keyName, releaseSlot);
    } catch (err) {
+      releaseSlot();
      return reject(err);
    }

@@ -982,6 +1174,8 @@ function callClaudeTui(model, messages, _conversationId, _keyName) {
    home: TUI_HOME,
    realHome: process.env.HOME,
    cwd: TUI_CWD,
+    port: PORT, // F7 fix: port-scopes the tmux session name so a sibling OCP instance on a
+                // different port never collides with this instance's reap/kill-server logic.
    wallclockMs: TUI_WALLCLOCK_MS,
    entrypointMode: TUI_ENTRYPOINT,
  }).then(({ text, entrypoint, truncated }) => {
@@ -1063,14 +1257,28 @@ 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" } });
+  }
+
  let ctx;
  try {
-    ctx = spawnClaudeProcess(model, messages, conversationId, authInfo.keyName);
+    ctx = spawnClaudeProcess(model, messages, conversationId, authInfo.keyName, releaseSlot);
  } catch (err) {
+    releaseSlot();
    return jsonResponse(res, 500, { error: { message: sanitizeError(err.message), type: "proxy_error" } });
  }

@@ -1263,12 +1471,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`);
@@ -1688,7 +1907,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;
@@ -1897,7 +2118,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);
    }
  }

@@ -1914,8 +2135,9 @@ async function handleChatCompletions(req, res) {
      try { res.end(); } catch {}
      return;
    }
-    // Sanitize error: strip internal file paths before sending to client
-    jsonResponse(res, 500, { error: { message: sanitizeError(err.message), type: "proxy_error" } });
+    // Sanitize error: strip internal file paths before sending to client.
+    // FIX ⑥: ConcurrencyOverflowError → 429 + Retry-After; all other errors → 500 (unchanged).
+    respondUpstreamError(res, err);
  }
 }

@@ -2076,6 +2298,31 @@ 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();
+        return {
+          mode: shm.isolated ? "isolated-scratch-home" : "real-home",
+          isolated: shm.isolated,
+          home: shm.isolated ? shm.home : null,
+          reason: 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
@@ -2364,7 +2611,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`);
@@ -2376,6 +2623,15 @@ 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.`);
    const tuiAuth = process.env.CLAUDE_CODE_OAUTH_TOKEN
@@ -2383,7 +2639,11 @@ server.listen(PORT, BIND_ADDRESS, () => {
      : "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();
+      // F7 fix: scope to THIS instance's own port (see reapStaleTuiSessions). includeLegacy:
+      // true ONLY here — the one-time boot reap is the designated point to claim orphaned
+      // bare-prefix ("ocp-tui-<uuid8>") zombie sessions left by a PRE-fix process generation
+      // of this same instance (no live post-fix instance ever creates that shape again).
+      const n = reapStaleTuiSessions({ port: PORT, includeLegacy: true });
      if (n) logEvent("info", "tui_reaped_stale_sessions", { count: n });
    } catch {}
  }
@@ -1340,23 +1340,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";
@@ -1663,12 +1652,23 @@ await asyncTest("readTuiTranscript throws when no text and cap elapses", async (
 });

 // ── TUI session reaper ───────────────────────────────────────────────────
-import { reapStaleTuiSessions, SESSION_PREFIX, buildTuiCmd } from "./lib/tui/session.mjs";
+import { reapStaleTuiSessions, sessionPrefixForPort, LEGACY_SESSION_PREFIX, LEGACY_SESSION_NAME_RE, buildTuiCmd } from "./lib/tui/session.mjs";

 console.log("\nTUI session reaper:");

-test("SESSION_PREFIX is ocp-tui-", () => {
-  assert.equal(SESSION_PREFIX, "ocp-tui-");
+// F7 fix: the session prefix is instance-scoped by listen port so a second OCP
+// instance on the same host (different port) is never mistaken for "ours".
+test("sessionPrefixForPort embeds the port (F7 instance scoping)", () => {
+  assert.equal(sessionPrefixForPort(3456), "ocp-tui-3456-");
+  assert.equal(sessionPrefixForPort(4000), "ocp-tui-4000-");
+  assert.notEqual(sessionPrefixForPort(3456), sessionPrefixForPort(4000));
+});
+
+test("LEGACY_SESSION_NAME_RE matches only the exact old bare-prefix shape, never the new shape", () => {
+  assert.ok(LEGACY_SESSION_NAME_RE.test(`${LEGACY_SESSION_PREFIX}a1b2c3d4`), "legacy 8-hex shape matches");
+  assert.ok(!LEGACY_SESSION_NAME_RE.test("ocp-tui-3456-a1b2c3d4"), "new port-scoped shape must NOT match legacy regex");
+  assert.ok(!LEGACY_SESSION_NAME_RE.test("ocp-tui-a1b2c3"), "too-short suffix must not match");
+  assert.ok(!LEGACY_SESSION_NAME_RE.test("ocp-tui-a1b2c3d4extra"), "trailing extra chars must not match");
 });

 console.log("\nTUI command construction (proxy-purity / #4):");
@@ -1740,7 +1740,7 @@ test("buildTuiCmd shq-escapes a token containing shell metacharacters (no inject
 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];
    }
  };
@@ -1752,20 +1752,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");
-
-    // 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");
+    assert.ok(!full.includes("--dangerously-skip-permissions"), "skip-permissions branch is removed (bricks headless TUI)");

    // 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)");
@@ -1781,22 +1775,40 @@ test("buildTuiCmd OCP_TUI_FULL_TOOLS=1 grants -p-equivalent tool surface (single
  }
 });

-test("reaper kills ONLY ocp-tui- sessions, never olp-tui-", () => {
+test("reaper kills ONLY this instance's own port-scoped sessions, never olp-tui-", () => {
  const killed = [];
  const fakeTmux = (args) => {
-    if (args[0] === "list-sessions") return { status: 0, stdout: "ocp-tui-aaaa\nolp-tui-bbbb\nmisc\nocp-tui-cccc\n" };
+    if (args[0] === "list-sessions") return { status: 0, stdout: "ocp-tui-3456-aaaa\nolp-tui-bbbb\nmisc\nocp-tui-3456-cccc\n" };
    if (args[0] === "kill-session") { killed.push(args[args.indexOf("-t") + 1]); return { status: 0 }; }
    return { status: 0, stdout: "" };
  };
-  const n = reapStaleTuiSessions({ tmux: fakeTmux });
+  const n = reapStaleTuiSessions({ tmux: fakeTmux, port: 3456 });
  assert.equal(n, 2);
-  assert.equal(killed.join(","), "ocp-tui-aaaa,ocp-tui-cccc");
+  assert.equal(killed.join(","), "ocp-tui-3456-aaaa,ocp-tui-3456-cccc");
  assert.ok(!killed.includes("olp-tui-bbbb"), "olp-tui-bbbb must never be killed");
 });

+// F7 fix: a second OCP instance on the same host (different port) must be treated exactly
+// like a foreign product prefix — never reaped, never allowed to trigger kill-server.
+test("reaper treats a sibling OCP instance on a DIFFERENT port as foreign (F7)", () => {
+  const killed = [];
+  const calls = [];
+  const fakeTmux = (args) => {
+    calls.push(args.join(" "));
+    if (args[0] === "list-sessions") return { status: 0, stdout: "ocp-tui-3456-aaaa\nocp-tui-9999-bbbb\n" };
+    if (args[0] === "kill-session") { killed.push(args[args.indexOf("-t") + 1]); return { status: 0 }; }
+    return { status: 0, stdout: "" };
+  };
+  const n = reapStaleTuiSessions({ tmux: fakeTmux, port: 3456 });
+  assert.equal(n, 1, "killed only the own-port session");
+  assert.equal(killed.join(","), "ocp-tui-3456-aaaa");
+  assert.ok(!killed.includes("ocp-tui-9999-bbbb"), "sibling instance's session (port 9999) must NEVER be killed");
+  assert.ok(!calls.includes("kill-server"), "kill-server MUST NOT fire — sibling instance's session still live");
+});
+
 test("reaper returns 0 when tmux status !== 0 (no server)", () => {
  const fakeTmux = (_args) => ({ status: 1, stdout: "" });
-  const n = reapStaleTuiSessions({ tmux: fakeTmux });
+  const n = reapStaleTuiSessions({ tmux: fakeTmux, port: 3456 });
  assert.equal(n, 0);
 });

@@ -1807,7 +1819,7 @@ test("reaper returns 0 for empty session list", () => {
    if (args[0] === "kill-session") { killed.push(args[args.indexOf("-t") + 1]); return { status: 0 }; }
    return { status: 0, stdout: "" };
  };
-  const n = reapStaleTuiSessions({ tmux: fakeTmux });
+  const n = reapStaleTuiSessions({ tmux: fakeTmux, port: 3456 });
  assert.equal(n, 0);
  assert.equal(killed.length, 0);
 });
@@ -1820,10 +1832,10 @@ test("reaper kill-servers when the server is ours-only (flush defunct claude zom
  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" };
+    if (args[0] === "list-sessions") return { status: 0, stdout: "ocp-tui-3456-aaaa\nocp-tui-3456-bbbb\n" };
    return { status: 0, stdout: "" };
  };
-  const n = reapStaleTuiSessions({ tmux: fakeTmux });
+  const n = reapStaleTuiSessions({ tmux: fakeTmux, port: 3456 });
  assert.equal(n, 2, "killed both of our sessions");
  assert.ok(calls.includes("kill-server"), "kill-server fired — reaps the defunct backlog");
 });
@@ -1832,10 +1844,10 @@ test("reaper does NOT kill-server when a foreign (non-ocp) session remains (coex
  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" };
+    if (args[0] === "list-sessions") return { status: 0, stdout: "ocp-tui-3456-aaaa\nolp-tui-bbbb\n" };
    return { status: 0, stdout: "" };
  };
-  const n = reapStaleTuiSessions({ tmux: fakeTmux });
+  const n = reapStaleTuiSessions({ tmux: fakeTmux, port: 3456 });
  assert.equal(n, 1, "killed only our own session");
  assert.ok(!calls.includes("kill-server"), "kill-server MUST NOT fire — would disrupt olp-tui-*");
 });
@@ -1843,10 +1855,61 @@ test("reaper does NOT kill-server when a foreign (non-ocp) session remains (coex
 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 });
+  reapStaleTuiSessions({ tmux: fakeTmux, port: 3456 });
  assert.ok(!calls.includes("kill-server"), "no server → no kill-server (early return)");
 });

+// Legacy migration (F7): pre-fix versions created bare-prefix `ocp-tui-<uuid8>` sessions with
+// no port segment. includeLegacy is the boot-only opt-in that claims these as our own leftover
+// zombies; the periodic sweep never sets it, so a lingering legacy session cannot trigger
+// kill-server on a routine 15-minute tick.
+console.log("\nTUI legacy-prefix migration (boot-only reap, F7):");
+
+test("reaper leaves legacy bare-prefix sessions untouched by default (includeLegacy unset)", () => {
+  const killed = [];
+  const calls = [];
+  const fakeTmux = (args) => {
+    calls.push(args.join(" "));
+    if (args[0] === "list-sessions") return { status: 0, stdout: "ocp-tui-3456-aaaa\nocp-tui-deadbeef\n" };
+    if (args[0] === "kill-session") { killed.push(args[args.indexOf("-t") + 1]); return { status: 0 }; }
+    return { status: 0, stdout: "" };
+  };
+  const n = reapStaleTuiSessions({ tmux: fakeTmux, port: 3456 });
+  assert.equal(n, 1, "killed only the own-port session");
+  assert.ok(!killed.includes("ocp-tui-deadbeef"), "legacy session must NOT be reaped without includeLegacy");
+  assert.ok(!calls.includes("kill-server"), "legacy session blocks kill-server when not claimed");
+});
+
+test("reaper claims legacy bare-prefix sessions when includeLegacy=true (boot-time migration)", () => {
+  const killed = [];
+  const calls = [];
+  const fakeTmux = (args) => {
+    calls.push(args.join(" "));
+    if (args[0] === "list-sessions") return { status: 0, stdout: "ocp-tui-3456-aaaa\nocp-tui-deadbeef\n" };
+    if (args[0] === "kill-session") { killed.push(args[args.indexOf("-t") + 1]); return { status: 0 }; }
+    return { status: 0, stdout: "" };
+  };
+  const n = reapStaleTuiSessions({ tmux: fakeTmux, port: 3456, includeLegacy: true });
+  assert.equal(n, 2, "both own-port and legacy sessions reaped");
+  assert.ok(killed.includes("ocp-tui-deadbeef"), "legacy session claimed as our own leftover");
+  assert.ok(calls.includes("kill-server"), "kill-server fires once no foreign/unclaimed session remains");
+});
+
+test("reaper with includeLegacy=true still spares a sibling instance's port-scoped session", () => {
+  const killed = [];
+  const calls = [];
+  const fakeTmux = (args) => {
+    calls.push(args.join(" "));
+    if (args[0] === "list-sessions") return { status: 0, stdout: "ocp-tui-3456-aaaa\nocp-tui-deadbeef\nocp-tui-9999-zzzz\n" };
+    if (args[0] === "kill-session") { killed.push(args[args.indexOf("-t") + 1]); return { status: 0 }; }
+    return { status: 0, stdout: "" };
+  };
+  const n = reapStaleTuiSessions({ tmux: fakeTmux, port: 3456, includeLegacy: true });
+  assert.equal(n, 2, "own-port + legacy reaped, sibling instance untouched");
+  assert.ok(!killed.includes("ocp-tui-9999-zzzz"), "sibling instance session must never be claimed as legacy");
+  assert.ok(!calls.includes("kill-server"), "sibling instance's live session still blocks kill-server");
+});
+
 // ── 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";
@@ -1929,56 +1992,6 @@ test("resolveTuiHome: explicit OCP_TUI_HOME wins regardless of env token (back-c
  assert.equal(resolveTuiHome({ realHome: "/home/u", configuredHome: "/custom/home", envTokenSet: false }), "/custom/home");
 });

-// ── resolveTuiEntrypointEnv ───────────────────────────────────────────────
-import { resolveTuiEntrypointEnv } from "./lib/tui/session.mjs";
-
-console.log("\nresolveTuiEntrypointEnv:");
-
-test("mode 'cli' sets CLAUDE_CODE_ENTRYPOINT=cli", () => {
-  const env = {};
-  resolveTuiEntrypointEnv(env, "cli");
-  assert.equal(env.CLAUDE_CODE_ENTRYPOINT, "cli");
-});
-
-test("mode 'cli' overwrites an inherited CLAUDE_CODE_ENTRYPOINT value", () => {
-  const env = { CLAUDE_CODE_ENTRYPOINT: "sdk-cli" };
-  resolveTuiEntrypointEnv(env, "cli");
-  assert.equal(env.CLAUDE_CODE_ENTRYPOINT, "cli");
-});
-
-test("mode 'auto' deletes CLAUDE_CODE_ENTRYPOINT (leaves unset)", () => {
-  const env = {};
-  resolveTuiEntrypointEnv(env, "auto");
-  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", () => {
-  const env = { CLAUDE_CODE_ENTRYPOINT: "sdk-cli" };
-  resolveTuiEntrypointEnv(env, "auto");
-  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) ──
 import { TuiSemaphore, recordTuiEntrypoint, buildTuiHealthBlock } from "./lib/tui/semaphore.mjs";

@@ -2046,6 +2059,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", () => {
Author	SHA1	Message	Date
taodengandClaude Fable 5	ef690b54c8	fix(tui): scope session prefix + reap/kill-server to this instance's port (F7) Audit finding F7 (LOW): lib/tui/session.mjs hardcoded SESSION_PREFIX = "ocp-tui-" as a bare, host-wide constant. The boot-reap and periodic idle-reap in server.mjs used it to decide which tmux sessions to kill-session and whether to kill-server (which flushes defunct <claude> zombies but tears down the WHOLE tmux server, including any live pane). The coexistence guard only ever spared foreign product prefixes (olp-tui-); a SECOND OCP instance on the same host — e.g. a temporary verification instance stood up alongside production, a real pattern used during PR #144/#146 verification — was indistinguishable from "ours" and could have its LIVE sessions reaped/kill-server'd by the other instance's boot or periodic sweep. Fix: scope the session-name prefix to this instance's own listen port (the natural stable per-instance discriminator on one host — two OCP instances cannot share a port): `ocp-tui-<port>-`. A sibling instance's `ocp-tui-<otherPort>-` sessions now fail the own-prefix startsWith check and fall into the same "othersRemain" bucket as olp-tui-*, so they are never touched and never used to justify kill-server. lib/tui/session.mjs: - sessionPrefixForPort(port) replaces the bare SESSION_PREFIX export. - reapStaleTuiSessions({ tmux, port, includeLegacy }) now requires port and computes its own prefix from it. - runTuiTurn({ ..., port }) builds the tmux session name from sessionPrefixForPort(port) instead of the old bare constant. - LEGACY_SESSION_PREFIX / LEGACY_SESSION_NAME_RE (exact "ocp-tui-<8-hex>" shape, no port segment) describe the OLD pre-fix session-name shape, retained only for the migration below. Legacy migration rule (chosen + reasoning): a bare-prefix legacy session cannot be created by any post-fix OCP process, so if one is seen it is presumed to be an orphaned zombie from THIS instance's own PRE-fix process generation (left behind across an in-place upgrade), not a stranger's. reapStaleTuiSessions() therefore accepts an includeLegacy flag: server.mjs's one-time BOOT reap passes includeLegacy: true (claims exact-legacy-shape sessions as its own, enabling cleanup right after an upgrade); the periodic 15-min idle sweep does NOT set it, so a lingering legacy-shaped session during steady-state is conservatively treated as foreign and cannot trigger kill-server on a routine tick. Residual (documented, accepted): a genuinely-still-running PRE-fix OCP instance coexisting on the host at the exact moment a new instance boots could have its live legacy session reaped — the same class of residual risk the audit finding itself accepts ("no live instance of the new version creates them"); this PR does not regress that scenario, it only removes the far more common same-version collision that is the actual F7 finding. LEGACY_SESSION_NAME_RE (`^ocp-tui-[0-9a-f]{8}$`) can never match the new shape: the new shape always inserts a literal "-" between the port digits and the 8-hex suffix, which the anchored 8-hex-only legacy regex cannot satisfy. server.mjs changes are local TUI session-lifecycle infrastructure (tmux session naming, boot/periodic reap, kill-server) with no cli.js wire analogue — verified via `strings` against the compiled claude CLI 2.1.198 binary (this machine ships cli.js as a Mach-O binary per ALIGNMENT.md's "OAuth token-host verification" precedent): cli.js contains only `env.TMUX` detection (whether IT is running inside a tmux pane) and an unrelated `--remote-control-session-name-prefix` flag for its own remote-control feature — no session-prefix/reap/ kill-server mechanism of any kind. Per ALIGNMENT.md Rule 2, this is declared absent: no endpoint, header, request, or response shape changed; only OCP's own local process-lifecycle bookkeeping. No PORT literal was hardcoded (CI port-SPOT check) — PORT is threaded through from the existing server.mjs SPOT (lib/constants.mjs DEFAULT_PORT via CLAUDE_PROXY_PORT). test-features.mjs: rewrote the reaper suite's fixture session names to the new port-scoped shape, added tests for sessionPrefixForPort(), LEGACY_SESSION_NAME_RE's non-collision with the new shape, a sibling same-host OCP instance being treated as foreign (F7 regression test), and the includeLegacy boot-migration behavior (claims legacy zombies, still spares a sibling instance's port-scoped session). Verified: node --check server.mjs && node --check lib/tui/session.mjs && npm test → 243 passed, 0 failed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-07 22:37:58 +10:00
dtzp555-max GitHub taodeng	2922d68842	fix(server): re-resolve -p spawn OAuth token per-spawn, expiry-aware (③ regression) (#146 ) The FIX-③ spawn-home isolation memoized the OAuth token at startup. The macOS keychain access token rotates (~hourly, refreshed by the operator's real claude), so the startup snapshot went stale and every isolated -p spawn returned upstream 401 'Invalid authentication credentials' — a ~31h Mac-mini outage (PI231/oracle use static long-lived env tokens, unaffected). Fix: getSpawnHomeMode() now caches only the isolation DECISION; the token is re-resolved FRESH per spawn via resolveSpawnToken(), which also returns null when a known expiry has passed (5-min buffer) so the caller falls back to real HOME — where the spawned claude refreshes the credential natively and self-heals. OCP still never refreshes the token itself (a refresh-token grant would consume the single-use token and log out the operator's real claude — issue #112). Env-token hosts carry no expiresAt and are never expiry-gated. Infra/process change; no cli.js surface, no new endpoint/header. 238 tests pass; live-verified sonnet 200 on a temp instance. Co-authored-by: dtzp555 <dtzp555@gmail.com>	2026-06-26 20:35:21 +10:00
dtzp555-max GitHub taodeng Claude Sonnet 4.6	38da104b97	chore(release): v3.21.0 — TUI cleanup + client-tools/ToS docs + promotion plan (#145 ) * refactor(tui): dead-code / footgun cleanup (A1/A2/A3) ALIGNMENT.md Rule 2: infra-only, no new cli.js wire behavior. No protocol, no endpoint, no credential changes. A1 (session.mjs): delete resolveTuiEntrypointEnv() and its call site + the redundant env-strip block around the spawnSync call. The function mutated a {env} object passed to spawnSync (tmux itself), but tmux does NOT forward that env to the pane; the pane's claude gets its env ONLY from the `env` prefix string built inside buildTuiCmd (verified live 2026-06-01). The spawnSync {env} is intentionally minimal now; only env.HOME is retained (tmux binary reads it). All claude-specific vars go via the buildTuiCmd prefix string, unchanged. Tests for the now- deleted function removed; test count drops by 7 (expected). A2 (transcript.mjs): delete encodeCwd() and transcriptPath() exports. Production resolves transcripts exclusively via findTranscriptPath() (glob by session-id); these two helpers carried a fragile path-encoding rule used only by their own tests. grep confirms zero non-test importers. Added a TODO comment near findTranscriptPath() noting a CI fixture- contract test would make claude-schema drift fail loudly. Tests removed; count drops by 2. A3 (session.mjs + README): remove the CLAUDE_SKIP_PERMISSIONS branch that pushed --dangerously-skip-permissions when OCP_TUI_FULL_TOOLS=1. OCP_TUI_FULL_TOOLS=1 now always takes the --allowedTools path. Rationale: claude v2.1.x shows an interactive bypass-acceptance screen that a headless tmux TUI cannot answer — bricks the turn (tui_paste_not_landed / wallclock cap), not recoverable without a human. The working path is --allowedTools + scratch-home settings.json additionalDirectories. README OCP_TUI_FULL_TOOLS row updated to document the removal and the correct alternative; CLAUDE_SKIP_PERMISSIONS row for the -p path is unchanged (still used in server.mjs). Test updated: skip-permissions case replaced with an assertion that --dangerously-skip-permissions is absent from the full-tools command. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: client-tools boundary, ToS honesty, promotion plan (B1/B2/B3) ALIGNMENT.md Rule 2: docs-only, no new cli.js wire behavior. No protocol, endpoint, or credential changes. B1 (README): add 'Client-tools boundary' subsection under 'How It Works'. Documents that 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). B2 (README): two updates to 'Why OCP?' and the LAN-sharing section. (a) New bullet: 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). (b) LAN-sharing paragraph strengthened: 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. Replaces the softer 'account terms are your call' language. Feature and auth-mode docs are unchanged. B3 (docs/PROMOTION.md): new promotion strategy doc. Covers: 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, gateway model-discovery — delegated to OLP; 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. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore(release): v3.21.0 — TUI cleanup + docs honesty + promotion plan ALIGNMENT.md Rule 2: release prep; no new cli.js wire behavior. Bump version 3.20.1 → 3.21.0. CHANGELOG entry covers: - A1/A2/A3 TUI dead-code removals (inert entrypoint-env path, test-only transcript helpers, headless-unusable skip-permissions) - B1/B2/B3 docs (client-tools boundary, ToS honesty, Why-OCP posture, promotion plan) - Previously-shipped v3.20.x items documented for completeness: spawn-home isolation, bounded concurrency queue + 429, ocp restart, ocp-plugin OpenClaw compat. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: dtzp555 <dtzp555@gmail.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-06-25 11:50:06 +10:00
dtzp555-max GitHub taodeng Claude Opus 4.8	5aaab5ea28	fix: -p spawn-home isolation (③ latency 3x) + concurrency queue/429 (⑥) + ocp restart env + /ocp plugin compat (#144 ) * fix(server): isolate default -p spawn in credential-free scratch HOME (latency ③) The default (-p/stream-json) spawn inherited the operator's real HOME (global ~/.claude plugins/skills/hooks) and ran with cwd=~/ocp (project CLAUDE.md/skills), loading heavy host context on EVERY request. Measured: pure API floor for haiku "hi" ≈ 1–2s; same CLI in the operator's real HOME/cwd ≈ 10–28s; a clean minimal HOME + CLAUDE_CODE_OAUTH_TOKEN ≈ 3–7s with auth intact. When an OAuth token is resolvable (and OCP_SPAWN_REAL_HOME!=1), spawnClaudeProcess now runs claude under a credential-free minimal scratch HOME (<HOME>/.ocp/spawn-home, no .credentials.json / settings.json / plugins) with cwd = that neutral dir and the resolved token in CLAUDE_CODE_OAUTH_TOKEN (env token is authoritative for -p). Mirrors the TUI path's resolveTuiHome() env-token mode. Falls back to real HOME + inherited cwd when no token resolves (zero regression); OCP_SPAWN_REAL_HOME=1 is a kill-switch. The token is resolved ONCE (memoized via getSpawnHomeMode, reusing getOAuthCredentials, the same resolver the /usage probe uses) and never logged. Adds a startup log line and an additive /health `spawn` block so the operator can confirm isolation is on. ALIGNMENT.md Rule 2 justification: this is an INFRA / PROCESS-MANAGEMENT change (HOME/cwd/env isolation of the spawned process). It does NOT mirror a cli.js wire operation, introduces no new endpoint/header, and adds no API token to the wire path — so there is no cli.js function to cite. CLAUDE_CODE_OAUTH_TOKEN / CLAUDE_CODE_DISABLE_* are existing claude-CLI env contracts already used by the TUI path and getOAuthCredentials. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(server): bounded wait-queue + HTTP 429 for -p concurrency overflow (⑥) spawnClaudeProcess used `if (activeRequests >= MAX_CONCURRENT) throw` → the client got an opaque 500 AND the rejection was uncounted (a 15-concurrent stress run returned 7×500 while /health stats.errors stayed 0). The TUI path already had a bounded-queue semaphore (TuiSemaphore); the -p path did not. Now the -p path reuses TuiSemaphore as `claudeSemaphore = new TuiSemaphore(MAX_CONCURRENT, { maxQueue: CLAUDE_MAX_QUEUE })`. Requests beyond MAX_CONCURRENT WAIT (up to CLAUDE_MAX_QUEUE, default 16) instead of being rejected; only when the queue is ALSO full does the request get HTTP 429 + Retry-After (rate_limit_error, NOT 500), a distinct `concurrency_queue_full` log, and a stats.queueRejections counter surfaced on /health. callClaude / callClaudeStreaming now acquire a slot (acquireClaudeSlot) before spawning; the release fn is wired into the existing idempotent cleanup() so the slot is freed on EVERY exit path (close/error/timeout/abort) — the #37/#40 slot-leak guard. MAX_CONCURRENT semantics (max concurrent claude procs) are unchanged; only overflow handling changed from throw-500 to queue-then-429. claudeSemaphore.limit is kept in sync with runtime /settings maxConcurrent changes. Live-verified (fake claude, MAX_CONCURRENT=1 MAX_QUEUE=1): 3 concurrent → exactly one 429 (Retry-After: 7, rate_limit_error body) + two 200s, on BOTH the non-streaming and streaming paths; /health stats.queueRejections=1 while stats.errors=0; after drain activeRequests=0 / inflight=0 / queued=0 and a follow-up request returns 200 (no slot leak). 2 new unit tests (247 passed, 0 failed). ALIGNMENT.md Rule 2 justification: this is an INFRA / PROCESS-MANAGEMENT change (a concurrency queue + backpressure status code in front of the existing spawn). It does NOT mirror a cli.js wire operation, adds no new endpoint or wire header, and introduces no API token — so there is no cli.js function to cite. (Retry-After is a standard HTTP response header on OCP's own 429, not a claude wire header.) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(ocp): macOS restart uses bootout+bootstrap so plist env is re-read The macOS restart path used `launchctl kickstart -k gui/$uid/dev.ocp.proxy`, which only re-execs the process and reuses launchd's CACHED environment — so a plist EnvironmentVariables edit (CLAUDE_BIND, CLAUDE_CODE_OAUTH_TOKEN, etc.) was silently ignored until a full unload/reload. This is the documented pit-index footgun. `ocp restart` (macOS) now does a full `launchctl bootout` + `bootstrap` of the agent via a new `_launchd_reload` helper, which re-reads the plist EnvironmentVariables so env changes take effect. Success is keyed on the bootstrap (the env-reloading load), not the bootout (which may legitimately fail if the agent is not currently loaded). A missing plist returns failure so the `elif` chain falls through to the legacy label and then to the Linux `systemctl --user restart` path unchanged (systemctl already re-reads its EnvironmentFile). Updates `ocp restart` help text and adds a README Troubleshooting subsection ("Env var change doesn't take effect after restart") with the manual bootout+bootstrap commands and a ps-based verification one-liner. Verified `_launchd_reload` with a stubbed launchctl: missing plist → rc=1 (falls through, no launchctl call); bootout-fail + bootstrap-ok → rc=0; bootstrap-fail → rc=1; call order is bootout then bootstrap. `bash -n ocp` clean; npm test 247/0 (server.mjs untouched). ALIGNMENT.md Rule 2 justification: this changes ONLY the `ocp` CLI wrapper's local service-restart mechanism (launchctl invocation). It does not touch server.mjs, the wire path, any endpoint/header, or any API token — so there is no cli.js function to cite. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(readme): document new env vars CLAUDE_MAX_QUEUE / CLAUDE_QUEUE_RETRY_AFTER / OCP_SPAWN_REAL_HOME Release_kit contract (CLAUDE.md Iron Rule 5.5: "new env var → README § Environment Variables table") requires the three env vars added by the perf/concurrency fixes to be in the README table. Adds rows for CLAUDE_MAX_QUEUE (16) + CLAUDE_QUEUE_RETRY_AFTER (5) (FIX ⑥ -p wait-queue + 429) and OCP_SPAWN_REAL_HOME (FIX ③ spawn-home isolation kill-switch), each cross-referencing the additive /health.concurrency and /health.spawn fields. Addresses the independent reviewer's MEDIUM finding. Docs only. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(ocp-plugin): add openclaw.extensions for OpenClaw 2026.5.27 compat + sync version (②/ocp) ocp-plugin/package.json's openclaw object lacked the 'extensions' field that OpenClaw 2026.5.27 requires to install/load a plugin (matches the sibling olp plugin). Without it the daemon refused to load the local path plugin, breaking /ocp Telegram commands. Version synced 3.12.0 -> 3.16.2 to match the manifest. Plugin-layer change; no server.mjs / ALIGNMENT cli.js surface touched. --------- Co-authored-by: dtzp555 <dtzp555@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-25 11:26:57 +10:00
dtzp555-max GitHub taodengClaude <claude-opus> <noreply@anthropic.com>	3bd19956ff	docs(readme): honest ToS framing for LAN sharing (#136 ) (#143 ) External user (#136) reported the LAN setup prompt instructs Claude to "share my Claude Pro/Max subscription with family" — which Claude Code refuses (Anthropic Usage Policy: per-user accounts). Reword the LAN setup prompt to "my own devices ... reach my subscription via a local OpenAI-compatible endpoint" (no longer triggers the refusal), and add an honest "account terms are your call" note to the existing sharing-limits section. Keeps the truthful origin story and the existing honest security-limits framing. Docs only. No server.mjs / Class A surface / models.json touched. Co-authored-by: dtzp555 <dtzp555@gmail.com> Co-authored-by: Claude <claude-opus> <noreply@anthropic.com>	2026-06-13 17:04:07 +10:00