Merge branch 'main' into preview

# Conflicts:
#	package.json

Author: lidge-jun

README.ko.md

@@ -247,6 +247,7 @@ ocx sync                       # 모델 갱신 + Codex에 재주입
 ocx status                     # 프록시 실행 중인지 확인
 ocx login <xai|anthropic|kimi> # OAuth 로그인
 ocx logout <provider>          # 저장된 로그인 정보 삭제
+ocx account <list|current|use> # 계정/API key pool 조회·전환 (마스킹; refresh/auto-switch/remove/add-key 포함)
 ocx gui                        # 웹 대시보드 열기
 ocx claude [args...]           # 프록시에 연결된 Claude Code 실행 (모델 디스커버리 켜짐)
 ocx codex-shim install         # codex 실행 시 `ocx ensure` 실행

README.md

@@ -280,6 +280,7 @@ ocx codex-shim install         # run `ocx ensure` whenever `codex` is launched
 ocx status                     # is the proxy running?
 ocx login <provider>          # OAuth login (xai, anthropic, kimi, cursor, ...)
 ocx logout <provider>          # remove a stored login
+ocx account <list|current|use> # list/switch accounts & API-key pools (masked; also refresh/auto-switch/remove/add-key)
 ocx gui                        # open the web dashboard
 ocx claude [args...]           # launch Claude Code wired to the proxy (model discovery on)
 ocx service [install|start|stop|status|uninstall]   # install/update/start background service

README.zh-CN.md

@@ -240,6 +240,7 @@ ocx sync                       # 刷新模型列表 + 重新注入 Codex
 ocx status                     # 查看代理是否在运行
 ocx login <xai|anthropic|kimi> # OAuth 登录
 ocx logout <provider>          # 移除已保存的登录
+ocx account <list|current|use> # 查看/切换账号与 API-key pool（脱敏；含 refresh/auto-switch/remove/add-key）
 ocx gui                        # 打开 Web 仪表盘
 ocx claude [args...]           # 启动接入代理的 Claude Code（模型发现已开启）
 ocx codex-shim install         # 运行 codex 时自动启动代理

bin/ocx.mjs

@@ -124,6 +124,37 @@ function runNpmSelfUpdate() {
     return [launcher, "service", "install"];
   }
 
+  // Capture listen target before stop clears runtime-port.json (mirrors GUI/CLI update worker).
+  // Do not treat a live runtime port of 10100 as "missing" — track whether the read succeeded.
+  let bakePort = 10100;
+  let sawRuntimePort = false;
+  try {
+    const rt = JSON.parse(readFileSync(join(configDir(), "runtime-port.json"), "utf8"));
+    if (Number.isFinite(rt?.port) && rt.port > 0 && rt.port <= 65535) {
+      // Only trust runtime when its pid still looks alive (stale crash leftovers fall back to config).
+      const rtPid = Number(rt?.pid);
+      let runtimeLive = false;
+      if (Number.isSafeInteger(rtPid) && rtPid > 0) {
+        try {
+          process.kill(rtPid, 0);
+          runtimeLive = true;
+        } catch (e) {
+          if (e && typeof e === "object" && "code" in e && e.code === "EPERM") runtimeLive = true;
+        }
+      }
+      if (runtimeLive) {
+        bakePort = Math.trunc(rt.port);
+        sawRuntimePort = true;
+      }
+    }
+  } catch { /* fall through to config */ }
+  if (!sawRuntimePort) {
+    try {
+      const cfg = JSON.parse(readFileSync(join(configDir(), "config.json"), "utf8"));
+      if (Number.isFinite(cfg?.port) && cfg.port > 0 && cfg.port <= 65535) bakePort = Math.trunc(cfg.port);
+    } catch { /* keep default */ }
+  }
+
   // Never replace package files under a live proxy — stop it first (full `ocx stop`
   // semantics: graceful drain, service stop, native Codex restore). Gate on the service
   // and the runtime-port record too: a service-managed or orphaned proxy can be live
@@ -163,9 +194,16 @@ function runNpmSelfUpdate() {
     // launcher so the new files write the baked paths and the service restarts.
     if (serviceWasInstalled) {
       console.log("Reinstalling the background service with the updated files...");
-      const svcArgs = serviceReinstallArgs();
-      const svc = spawnSync(process.execPath, svcArgs, { stdio: "inherit", windowsHide: true });
-      if (svc.status !== 0) console.warn("opencodex: service refresh failed — run 'ocx service install' manually.");
+      const prevBake = process.env.OCX_BAKE_PORT;
+      process.env.OCX_BAKE_PORT = String(bakePort);
+      try {
+        const svcArgs = serviceReinstallArgs();
+        const svc = spawnSync(process.execPath, svcArgs, { stdio: "inherit", windowsHide: true });
+        if (svc.status !== 0) console.warn("opencodex: service refresh failed — run 'ocx service install' manually.");
+      } finally {
+        if (prevBake === undefined) delete process.env.OCX_BAKE_PORT;
+        else process.env.OCX_BAKE_PORT = prevBake;
+      }
     } else {
       console.log("Restart the proxy:  ocx start");
     }

devlog/_fin/260721_unanswered_issue_triage/000_plan.md

@@ -0,0 +1,43 @@
+# Unanswered issue triage and fixes
+
+This work validates the unanswered issues open on 2026-07-21 before changing code.
+
+## Scope
+
+- #190: Cursor rejects an aggregate Codex tool catalog with `resource_exhausted`.
+- #181: provider deletion hides the server's actionable default-provider guard.
+- #198: usage/log cost estimates can be mistaken for actual billing.
+- #180 and #196: verify fixes already absorbed into `dev` instead of duplicating them.
+- #177 and #178: verify whether the vendors expose a model-inference contract that fits an OpenCodex provider.
+
+[Decision Log]
+- 목적과 의도: Validate each report against current `dev`, fix confirmed defects, and leave evidence-backed issue replies.
+- 기존 구현 및 제약 조건: Cursor registers client tools through a protobuf `McpTools` field with observed count and byte ceilings. The same filtered catalog must drive protobuf advertising and client tool-call recognition. GUI-visible text must be translated in every locale.
+- 검토한 주요 대안: Import the closed #192 heuristic patch; drop whole namespaces by count; stub schemas and move them into prompt text; measure actual serialized definitions and prioritize recoverable tools.
+- 선택한 방식: Measure the real serialized `McpTools` payload, enforce one hard count cap, prioritize explicit and `tool_search`-loaded tools, and skip oversized candidates while continuing to fill the catalog. Surface server delete errors directly and label cost values as non-billing list-price equivalents.
+- 다른 대안 대신 이 방식을 선택한 이유: The closed patch undercounted protobuf bytes, could exceed the count cap through reserved tools, and did not reliably promote searched tools. Exact serialization removes those failure modes without inventing an incompatible schema-stubbing protocol.
+- 장점, 단점 및 영향: The transport stays below both observed Cursor limits and searched tools become usable on the next turn. Some low-priority tools can still be omitted in very large catalogs, so the request includes an explicit recovery note when `tool_search` is available. Serialization adds bounded setup work once per Cursor turn.
+
+## Verification plan
+
+- Focused parser, Cursor request-builder/tool-definition/error tests.
+- GUI lint, i18n lint, TypeScript build, and relevant existing tests.
+- Full repository pre-push gate before pushing `dev`.
+
+## Result
+
+- #180 was already implemented on current `dev` as the complete `ocx account` command family. Its 41-case regression matrix passes; privacy-scan fixture strings were changed from token-shaped literals without changing behavior.
+- #196 was already absorbed on `dev`; the registry and three Qwen 3.8 reasoning replay tests pass.
+- #190 now budgets the exact serialized `McpTools` protobuf to 120,000 bytes and 330 definitions, prioritizes explicit/native and tool-search-loaded definitions, and classifies residual catalog exhaustion as HTTP 400 `tool_catalog_too_large` rather than a quota rate limit.
+- #181 now displays the management API's structured delete error, with a translated fallback for network, empty, or malformed responses.
+- #198 now labels dashboard cost values as API list-price equivalents rather than charges in English, Korean, German, and Chinese, with matching public documentation.
+- #177 and #178 remain feature requests: Warp documents an asynchronous Oz agent-run API, while Factory documents configuring upstream model gateways for its own client. Neither public contract is an OpenAI-compatible model-inference endpoint that can be registered as an OpenCodex provider without a new adapter contract.
+
+## Verification result
+
+- Full repository suite: 3,296 passed, 0 failed before the fixture-only privacy repair.
+- Post-repair focused suite: 94 passed, 0 failed for Cursor error/catalog handling, request logging, and the #180 CLI matrix.
+- Root TypeScript typecheck passed.
+- GUI ESLint, i18n lint, and production build passed.
+- Privacy scan passed.
+- React Doctor full scan completed; it reported the repository's existing baseline (197 diagnostics, including one pre-existing `Models.tsx` state-updater error). No new diagnostic was introduced by these changes.

docs-site/src/content/docs/guides/providers.md

@@ -137,6 +137,13 @@ under `provider.apiKeyPool`, makes it active, and mirrors it to `provider.apiKey
 adapters continue to read the same field as before. The same dropdown can switch or remove keys; the
 management API is `/api/providers/keys` and returns masked keys only.
 
+### Switching accounts from the terminal
+
+Use `ocx account list`, `ocx account current`, and `ocx account use` to inspect or switch the same
+Codex, OAuth, and API-key pools without opening the dashboard. See the
+[CLI reference](/opencodex/reference/cli/#ocx-account-subcommand) for commands, JSON output, and
+new-session behavior.
+
 ### GPT-5.6 preview paths
 
 GPT-5.6 Sol/Terra/Luna are seeded in provider fallback lists so `ocx sync` can keep the models

docs-site/src/content/docs/guides/web-dashboard.md

@@ -39,6 +39,10 @@ bun run dev:gui
 | **Usage / Debug** | Inspect token-usage coverage and trends, or enable opt-in provider transport and usage-extraction diagnostics. |
 | **Stop** | Gracefully stop the proxy and installed background service, restore native Codex, and exit (`POST /api/stop`). |
 
+Cost values in **Logs** and **Usage** are API list-price equivalents calculated from reported tokens.
+They are not billing receipts or evidence of an actual charge; subscription usage or provider credits
+may apply instead.
+
 ## Delegation picker vs spawn routing
 
 The Dashboard's **Sub-agent delegation** picker stores `injectionModel` and, optionally,

docs-site/src/content/docs/ko/guides/providers.md

@@ -134,6 +134,12 @@ opencodex v2.7.1에는 빌트인 프리셋이 50개 들어 있습니다. 키 방
 `provider.apiKey`에도 반영합니다. 같은 드롭다운에서 키를 전환하거나 제거할 수 있습니다. 관리 API는
 `/api/providers/keys`이며 마스킹된 키만 반환합니다.
 
+### 터미널에서 계정 전환하기
+
+대시보드를 열지 않고도 `ocx account list`, `ocx account current`, `ocx account use`로 같은 Codex,
+OAuth, API-key pool을 확인하고 전환할 수 있습니다. 전체 명령, JSON 출력, 새 세션 적용 방식은
+[CLI 레퍼런스](/opencodex/ko/reference/cli/#ocx-account-subcommand)를 참고하세요.
+
 ### GPT-5.6 프리뷰 경로
 
 실시간 모델 카탈로그 갱신이 늦어도 `ocx sync`에서 모델이 사라지지 않도록 GPT-5.6

docs-site/src/content/docs/ko/guides/web-dashboard.md

@@ -39,6 +39,9 @@ bun run dev:gui
 | **Usage / Debug** | 토큰 사용량의 측정 범위와 추이를 보거나, 선택적 프로바이더 전송/사용량 추출 진단을 켭니다. |
 | **Stop** | 프록시와 설치된 백그라운드 서비스를 정상 종료하고 네이티브 Codex를 복원한 뒤 끝냅니다(`POST /api/stop`). |
 
+**Logs**와 **Usage**의 비용 값은 보고된 토큰으로 계산한 API 정가 환산치입니다. 결제 영수증이나
+실제 청구 증거가 아니며, 구독 사용량 또는 프로바이더 크레딧이 대신 적용될 수 있습니다.
+
 ## 위임 선택기와 스폰 라우팅의 차이
 
 Dashboard의 **Sub-agent delegation** 선택기는 `injectionModel`과 선택적인 `injectionEffort`를

docs-site/src/content/docs/ko/reference/cli.md

@@ -192,6 +192,135 @@ ocx provider show anthropic --json
 ocx models --provider anthropic --json
 ```
 
+### `ocx account <subcommand>`
+
+실행 중인 프록시를 통해 프로바이더 계정과 API-key pool을 조회하고 전환합니다. 배포된 도움말의
+명령 표면은 다음과 같습니다.
+
+```text
+Usage: ocx account <list|current|use|refresh|auto-switch|remove|add-key> ...
+
+List and switch provider accounts and API-key pools (GUI parity).
+
+list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
+current <provider>  Show the active account or key.
+use <provider> <id> Switch the active credential; 'main' selects the Codex App login.
+refresh <provider>  Force-refresh Codex or provider quota reports.
+auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.
+remove <provider> <id> --yes  Remove a stored account or key after an existence check.
+add-key <provider> [--label <label>]  Add a key read only from piped stdin.
+Codex pool switches apply to new sessions; running threads keep their account.
+```
+
+모든 하위 명령은 프록시가 실행 중이어야 하며 CLI가 기록된 런타임 포트를 자동으로 찾습니다. 성공은
+종료 코드 0을 반환합니다. 잘못된 사용법, 알 수 없는 프로바이더나 계정/key id, 프록시 연결 실패,
+API 오류는 종료 코드 1입니다. 자격 증명 필드는 management API가 반환한 그대로(API가 적용한
+마스킹 포함) 표시하며, 원본 API key와 OAuth token은 반환하지 않습니다. 화면 편의 값은 대시보드와
+같은 방식으로 CLI가 합성합니다: `main`은 `openai` 계정 풀의 Codex App 로그인 별칭이고, 이메일이
+없는 OAuth 계정은 `Account N`으로 표시되며, plan/label 열은 plan → 마스킹 이메일 → label →
+마스킹 key 순으로 대체합니다.
+
+`--json`의 계정 행은 아래 공통 형태를 사용합니다(값이 없으면 선택 필드는 생략됩니다).
+
+```json
+{
+  "provider": "openai",
+  "type": "codex | oauth | api-key",
+  "id": "__main__",
+  "label": "plus",
+  "email": "m***@example.com",
+  "plan": "plus",
+  "masked": "sk-ab****wxyz",
+  "active": true,
+  "needsReauth": false,
+  "quota": null
+}
+```
+
+#### `ocx account list [provider] [--json] [--all]`
+
+프로바이더를 생략하면 Codex pool, OAuth 계정, 설정된 API-key pool을 모두 나열합니다. 빈
+프로바이더는 `--all`을 지정하지 않으면 건너뛰며, 프로바이더를 지정하면 해당 자격 증명 family만
+조회합니다. 일반 출력 열은 `PROVIDER TYPE ID PLAN/LABEL STATUS`이고 고정된 Codex 행에는
+`next session`이 표시됩니다. 저장된 Kiro 계정이 있으면 로그인 슬롯이 하나이며 다시 로그인하면 현재 계정이
+교체된다는 안내가 나옵니다. 결과가 비어 있어도 성공입니다. `--json`은 다음을 반환합니다.
+
+```text
+{ accounts: AccountRow[], notes: string[] }
+```
+
+#### `ocx account current <provider> [--json]`
+
+활성 계정이나 key를 표시합니다. 수동 pin이 없는 Codex pool은 사용량이 가장 낮은 계정을 자동으로
+선택한다고 표시합니다. 다른 family에 활성 자격 증명이 없어도 그 상태를 알리고 종료 코드 0을
+반환합니다. `--json` 형태는 다음과 같습니다.
+
+```text
+{ provider, type, activeId: string | null, autoSwitchThreshold?: number, account: AccountRow | null }
+```
+
+#### `ocx account use <provider> <account-or-key-id|main> [--json]`
+
+기존 Codex 계정, OAuth 계정 또는 API key를 선택합니다. `openai`에서 `main`은 Codex App 로그인을
+선택합니다. Codex 선택은 **새 세션**부터 적용되며 기존 thread는 현재 계정을 유지합니다. auto-switch
+threshold가 켜져 있으면 나중에 수동 pin을 덮어쓸 수 있습니다. 알 수 없는 프로바이더나 id는 종료
+코드 1입니다. `--json`은 다음을 반환합니다.
+
+```text
+{ ok: true, provider, type, activeId }
+```
+
+#### `ocx account refresh <provider> [--json]`
+
+Codex pool은 `ocx account refresh openai [--json]`을 사용합니다. 계정 quota를 강제로 새로 고치고
+확인 가능한 주간/월간 백분율과 reset 시각을 표시합니다. quota 정보가 없으면 0%가 아니라 unknown으로
+표시합니다. JSON envelope은 `{ accounts: AccountRow[] }`이며 각 Codex 행에 `quota`가 들어갑니다.
+
+OAuth 및 API-key 프로바이더에서는 provider quota-report endpoint를 강제로 새로 고칩니다. token
+재로그인이나 단순 account-list 재조회가 아닙니다. `--json`은
+`{ provider, report: ProviderQuotaReport | null }`을 반환합니다. 지원되는 quota report가 없으면
+`no quota report available for <provider>`를 출력하고 종료 코드 0을 반환합니다. 알 수 없는
+프로바이더와 management API 오류는 종료 코드 1이며, upstream quota probe가 실패하거나 시간
+초과되면 대시보드의 quota 막대와 마찬가지로 null/오래된 report로 저하되어 종료 코드 0을
+반환합니다.
+
+#### `ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]`
+
+`openai` Codex 계정 pool만 제어합니다. `on`은 80%, `off`는 0%로 설정하고 `status`는 현재 값을
+읽습니다. `threshold <n>`은 0부터 100까지의 정수만 받습니다. 다른 프로바이더나 잘못된 값은 종료
+코드 1입니다. `--json`은 다음을 반환합니다.
+
+```text
+{ provider, autoSwitchThreshold: number, enabled: boolean }
+```
+
+#### `ocx account remove <provider> <id|main> --yes [--json]`
+
+보호된 비대화형 삭제이므로 `--yes`가 필수입니다. 삭제 전에 id 존재 여부를 확인하며, 없는 id는
+DELETE를 보내지 않고 종료 코드 1을 반환합니다. 메인 Codex App 로그인은 제거할 수 없으므로
+`remove openai main --yes`도 거부합니다. 삭제 후 family를 다시 읽습니다. 고정된 Codex 계정을
+지우면 pin이 해제되어 자동 선택으로 돌아가고, OAuth는 남은 첫 계정을 활성화하거나 계정 없음으로
+표시하며, API-key pool은 남은 첫 key를 활성화하거나 key 없음으로 표시합니다. `--json`의 성공/실패
+형태는 다음과 같습니다.
+
+```text
+{ ok: true, provider, id, removedActive: boolean, promotedActiveId: string | null }
+{ error: string } // stderr, exit 1
+```
+
+#### `ocx account add-key <provider> [--label <label>] [--json]`
+
+API-key 프로바이더에 key를 추가하고 활성화합니다. key는 TTY가 아닌 pipe/redirect stdin으로만
+읽습니다. 대화형 TTY 입력, 빈 입력, OAuth/Codex 프로바이더, API 오류는 종료 코드 1입니다. label
+안에 key가 들어 있어도 key를 절대 echo하지 않습니다. secret manager나 here-string을 사용하세요.
+
+```bash
+ocx account add-key openrouter --label personal <<< "$OPENROUTER_API_KEY"
+security find-generic-password -w openrouter | ocx account add-key openrouter --json
+```
+
+`--json`은 `{ ok: true, id: string | null, label?: string }`을 반환하며 key를 포함하지 않습니다.
+
 ## 인증
 
 ### `ocx login <provider>`