feat(proxy): add adaptive local port selection for OpenAI-compatible profiles

docs/codebase-summary.md

@@ -92,6 +92,20 @@ src/
 │   ├── unified-config-loader.ts  # Central config loader (546 lines)
 │   └── migration-manager.ts  # Config migration logic
 │
+├── proxy/                    # OpenAI-compatible proxy runtime
+│   ├── index.ts              # Barrel export
+│   ├── proxy-daemon-entry.ts # Daemon entrypoint
+│   ├── proxy-daemon.ts       # Lifecycle, health, and port binding
+│   ├── proxy-port-resolver.ts # Adaptive per-profile port selection
+│   ├── request-router.ts     # Request-time profile/model routing
+│   ├── profile-router.ts     # Profile resolution helpers
+│   ├── proxy-env.ts          # Local runtime env construction
+│   ├── routing-config.ts     # Proxy routing config parsing
+│   ├── upstream-url.ts       # Upstream endpoint resolution
+│   ├── proxy-daemon-state.ts # Persistent running-state metadata
+│   ├── server/               # HTTP server and routes
+│   └── transformers/         # Request and SSE translation
+│
 ├── channels/                 # Official Claude channel integration
 │   ├── official-channels-runtime.ts  # Runtime gating, plugin specs, setup guidance
 │   └── official-channels-store.ts    # Claude channel token/env storage helpers
@@ -216,6 +230,7 @@ src/
 | Targets | `bin/`, `targets/` | Multi-CLI adapter pattern (Claude Code, Factory Droid, Codex CLI, extensible) |
 | Auth | `auth/`, `cliproxy/auth/` | Authentication across providers |
 | Config | `config/`, `types/` | Configuration & type definitions |
+| OpenAI Proxy | `proxy/` | Adaptive local OpenAI-compatible proxy runtime, profile routing, and SSE transforms |
 | Providers | `cliproxy/`, `copilot/`, `glmt/` | Provider integrations plus retained legacy transformer internals |
 | Quota | `cliproxy/quota-*.ts`, `account-manager.ts` | Hybrid quota management (v7.14) |
 | Remote Proxy | `cliproxy/remote-*.ts`, `proxy-config-resolver.ts` | Remote CLIProxy support (v7.1) |

docs/openai-compatible-providers.md

@@ -32,7 +32,7 @@ When to use CCS:
 
 When you launch a compatible settings profile with the Claude target, CCS now:
 
-1. Starts a local proxy on `127.0.0.1`
+1. Starts a local proxy on `127.0.0.1` using the resolved local port for that profile
 2. Accepts Anthropic `/v1/messages` traffic from Claude Code
 3. Translates requests into OpenAI chat-completions format
 4. Forwards them to your configured upstream provider
@@ -72,12 +72,18 @@ Useful variants:
 
 ```bash
 ccs proxy start hf --host 127.0.0.1
+ccs proxy start hf --port 3460
 ccs proxy activate hf
 ccs proxy activate --fish
 ccs proxy status hf
 ccs proxy stop hf
 ```
 
+By default, CCS picks a deterministic local port for each compatible profile
+and adapts automatically when that port is unavailable. Use `--port` for a
+one-off pinned port, or set `proxy.profile_ports` in config when you want a
+stable reserved port per profile.
+
 `ccs proxy activate` now prints the full local runtime contract:
 
 - `ANTHROPIC_BASE_URL`
@@ -98,14 +104,15 @@ runtime as a singleton.
   running
 - When multiple proxies are running, pass the profile explicitly to
   `activate`, `status`, or `stop`
+- `status` and `activate` always reflect the actual running port instead of an
+  assumed default
 
-If you want deterministic ports, configure them in `~/.ccs/config.yaml`:
+If you want to pin ports explicitly, configure them in `~/.ccs/config.yaml`:
 
 ```yaml
 proxy:
-  port: 3456
   profile_ports:
-    hf: 3456
+    hf: 3460
     openai: 3461
 ```
 
@@ -301,10 +308,12 @@ That flag is respected by both:
 - Add `CCS_OPENAI_PROXY_INSECURE=1` to the profile settings
 - Restart the proxy after changing the setting
 
-### Port conflict on `3456`
+### Need to pin or verify the local port
 
-- Start with a fixed port: `ccs proxy start hf --port 3457`
-- Re-run `ccs proxy activate` after changing the port
+- Check the active binding with `ccs proxy status hf`
+- Pin a one-off port with `ccs proxy start hf --port 3460`
+- Reserve a stable profile port with `proxy.profile_ports`
+- Re-run `ccs proxy activate hf` after changing the port
 
 ### Provider returns `429` or empty upstream output