gettokens-domain-engineering

name	gettokens-domain-engineering
description	GetTokens 领域工程：账号池、quota、UI 体系、调试与 CLIProxyAPI fork。

GetTokens Domain & Engineering

This skill unifies the technical rules for building, styling, and debugging GetTokens.

1. Accounts Domain & Unified Inventory

• Model: Unified AccountRecord combining auth files (sidecar), API keys (local store), and Codex quota (projected telemetry).
• Rules:

  • Keep provider and credentialSource separate.

  • Uniqueness is by asset (e.g., auth-file:<name>).

  • codex api key records must prefer a persisted stable local id over a derived config fingerprint. Editing apiKey / baseUrl / prefix must not change the record id used by frontend selection, modal state, disable state, or rotation ordering.

  • User-created or copied codex api key records may share the same normalized config identity (apiKey + baseUrl + prefix). Treat each persisted local-id as a separate editable account asset; store files should be keyed by local-id so duplicates do not overwrite each other.

  • Legacy sidecar mirror data without local-id may still be deduplicated against a stored local record with the same normalized config identity to avoid reintroducing the historical double-card bug.

  • Account-card copy/import must copy a structured account payload, not just a display name. The payload should round-trip all supported asset classes: auth-file, codex-api-key, and openai-compatible.

  • Account-card clipboard writes must tolerate browser preview and Wails permission differences. Prefer a shared clipboard helper with DOM copy, Web Clipboard, Wails runtime, and app-local fallback paths instead of calling navigator.clipboard.writeText directly from card components.

  • Copied account imports create a new editable asset even when the underlying config is identical. When the imported title/provider/file name already exists, append user-facing numeric suffixes from #2 onward; do not use -copy style suffixes. For auth-file imports, preserve .json after the numbered title, such as codex-auth #2.json.

  • Account import file intake may accept common archives such as .zip, .tar, .tar.gz, .tgz, .json.gz, and .gzip. Use a mature compression library such as fflate for compressed layers; keep any TAR handling limited to archive entry enumeration. Archive handling is only a candidate-expansion step: scan internal .json entries, ignore directories / non-JSON files / __MACOSX, preserve archive-qualified names such as accounts.zip:nested/auth.json, and keep final session/auth normalization in the shared backend upload/import path.

  • Do not fetch accounts until sidecar is ready.

  • Reload from Wails after create/delete instead of hand-merging state.

  • Account inventory reads must not implicitly fan out into all-account quota, usage, and rate-limit reads. Load the safe inventory first, then schedule runtime supplements only for visible, selected, active-route, live-session, or explicitly refreshed accounts.

  • Automatic account runtime supplement reads must pass through one coordinator keyed by stable account id plus resource. Concurrent overlapping batches may refresh only missing account/resource pairs and must wait for existing in-flight work instead of duplicating it. When no visible/selected target is reported, do not fall back to refreshing the entire small account pool.

  • Version-like runtime metadata such as rate-limit strategies should use an App-lifetime singleflight loader and a separate failure domain from frequently refreshed per-account statuses. A strategy read failure must not erase an otherwise valid status response.

  • Account Runtime Authority V2 uses accounts-v2.sqlite as the only GetTokens runtime credential source. Legacy accounts-v1.sqlite, auth-dir/*.json, config API keys, FileTokenStore.List(), codex-api-key, and openai-compatibility are migration inputs only and must never become fallback runtime accounts.

  • OAuth refresh commit order is strict: upstream refresh result -> credential generation/token revision CAS in accounts-v2.sqlite -> in-memory auth/scheduler/hook update. A CAS conflict must leave memory, route guard, quota/rate-limit and hooks unchanged.

  • One active account compiles to exactly one runtime auth. Legacy openai-compatible assets containing multiple API key entries must be split into separate account assets during migration; runtime synthesis must not fan one account out into multiple auth IDs.

  • Every runtime auth enumeration entry point, including generic recursive token filestores, must prune migration-backups directories before reading JSON. Filtering only account-store synthesis is insufficient: a generic filestore can otherwise register backup OAuth files as orphan auths, refresh their consumed tokens, and project the resulting identity-level auth-error onto a current SQLite account with the same provider account_id.

  • The main account-store SQLite file is sidecar-owned. App/Wails must not directly sql.Open the primary accounts-v2.sqlite for account first-paint, details, diagnostics, or repair decisions. App-side fast reads must go through a sidecar management snapshot endpoint, or through a versioned sidecar-exported read-only projection that is explicitly limited to display data and never participates in runtime state decisions.

  • SQLite is the account truth source, but hot routing still depends on runtime AuthManager and ModelRegistry indexes. Account-store apply/refresh must rebuild those indexes even in embedded/no-watcher service mode; a card being applied in SQLite is not sufficient evidence that requests can route through it.

  • Account-store SQLite I/O failures such as SQLITE_IOERR_SHORT_READ / disk I/O error (522) are sidecar runtime failures, not frontend state issues. Fix them inside CLIProxyAPI account-store boundaries: upgrade/verify the SQLite driver, reset/reopen the cached store for recoverable read errors, retry read endpoints at most once, and return structured management errors such as code=account_store_io_error with recoverable=true. Account-card stale banners may summarize this as a user-readable cached-quota warning, but diagnostics surfaces must retain the raw error summary/tooltip for troubleshooting.

  • Account-store hot refresh must distinguish "read failed" from "valid empty account store". A configured-but-unreadable SQLite store must not be interpreted as an authoritative zero-account snapshot, because delete/update-triggered no-watcher refresh would otherwise prune every existing account-store runtime auth and make Codex relay return auth_unavailable until restart. Preserve existing runtime auths on read failure, surface the structured account-store error, and only prune when ListAccounts succeeds with an actual empty active set.

  • Account deletion remains soft-delete on the request path: set account_cards.deleted_at_unix_ms first, cancel matching runtime jobs, and reapply the account store once. Physical deletion belongs to a sidecar-owned idle cleanup worker that hard-deletes old soft-deleted account_cards in bounded batches, relies on SQLite ON DELETE CASCADE for credential/runtime rows, uses a retention window so recent mistakes remain recoverable, and must never run inside frontend loops.

  • Account deletion's immediate runtime effect must be targeted by account_key: after SQLite soft-delete succeeds, remove/disable only matching account-store runtime auths, unregister only their models, prune only their live sessions / websocket pins, and bump the pool epoch. Full account-store reconcile remains as a later consistency check, not the only way for a single delete to take effect and not a reason to mutate unrelated accounts.

  • Removing an account-store runtime auth must also clear every route-guard source owned by that auth before retaining its disabled tombstone. Healthy credential replacement / OAuth reauthorization must clear transient guards through the same full-auth lookup. Route guard blocks may be owned by auth id or account key and indexed by file name plus provider account identity; clearing only auth.ID is insufficient for quota/runtime blocks that carry only AccountKey. Use one route-guard API that expands the complete auth lookup keys instead of reconstructing identity rules in service code.

  • codex api key lives in local storage under ~/.config/gettokens-data/codex-api-keys/, not in auth-dir.

  • AccountsPage is route-only; heavy assembly lives under frontend/src/features/accounts/.

  • Feature-internal layering for accounts is:

    • components/
    • hooks/
    • model/
    • tests/

  • Do not re-introduce helpers.ts-style catch-all files. Split by responsibility such as config snippets, selectors, presentation, quota formatting, and actions.

  • Account list filters must not be collapsed into a single enum once source and availability semantics diverge. For account list and Codex account order filters, use AND-style requirement fields instead of a single availability enum or *Only compatibility fields:

    • source
    • requiresRequestable
    • requiresBlocked
    • requiresDisabled
    • hasBalance
    • hasLongestQuota
    • requiresError

  • Keep disabled and error/unavailable filters separate. A manually disabled account is route-excluded by user intent, while an error/unavailable account needs diagnostic attention.

  • Account-list status filters and status grouping must consume the same operational auth/quota failure evidence as account cards. 可请求 / requestable means active/configured/routeable and not blocked by terminal quota/runtime evidence such as blocked=true with sources[].source=auth-error or real stale + degradedReason; those accounts belong in 异常 / error instead. 已禁用 remains an explicit user/system disabled bucket, separate from operational error.

  • Account-card top-level operational state must consume runtime stale/degradedReason and sidecar route-guard source evidence, not only fresh usage/quota success. For OAuth/auth-file quota refresh failures with a real degraded reason, or route runtime blocked=true with sources[].source=auth-error, show the card as status_error_display / danger instead of falling back to "waiting check" or "available" whether the reason is terminal upstream failure (401/402/403, unauthorized, token_expired, invalidated, deactivated_workspace, etc.) or a generic refresh error (management api-call failed, refresh_failed, etc.). This auth/quota failure evidence must be evaluated before runtimeStatus=registered_routeable; being registered only proves the auth existed in runtime, not that the current OAuth credential is still usable. The card visual tint must follow the operational tone as well: danger maps to the critical/danger tint and must not fall back to routeable/positive coloring. Keep only explicit placeholder/unknown reasons such as "Quota runtime status has not been observed yet." in the waiting-check path. Codex account-list requestability remains a separate eligibility chain.

  • Sidecar management account read models must also project active route guard evidence. GET /v0/management/accounts and GET /v0/management/accounts/:account_key should overlay active AccountRouteGuardStore blocks as display/runtime evidence such as runtime_routeability_status=degraded, runtime_failure_class=<source>, and runtime_routeability_reason=<reason>, while leaving SQLite account_runtime_apply_state unchanged. Do not persist a transient auth-error, quota-empty, rate-limit, or upstream block by rewriting account-store routeability from a read path.

  • Persist account-list filter preferences separately from ephemeral UI state. Persist filters; do not persist search drafts, modal open state, or bulk-selection state unless a later requirement explicitly needs that.

  • Account plan is runtime data, not a fixed frontend enum. Account list grouping, badges, and plan filters must aggregate plan keys from AccountRecord.planType and quota planType; new values such as team, enterprise, billing, or provider-specific plan keys must form their own groups/options instead of falling into unknown merely because the frontend has not hard-coded them. Old all-selected plan filter state should not hide newly discovered plan keys.

  • Browser preview fixtures for account-list filters must include representative samples for every runtime-derived facet being shipped. If a rollout adds dynamic request-status filters such as HTTP 401/402/... or splits resource filters into quota/balance/usage facets, update frontend/src/features/accounts/previewData.ts so preview mode exposes at least one matching account per new facet; otherwise headless browser acceptance can prove only layout, not that the new filter group actually renders or narrows results.

  • When Wails dev App cards and external browser cards appear inconsistent, classify the evidence before changing card logic: first confirm whether the page has Wails bindings and which sidecar/profile/port it is reading, then compare per-window UI view-state and localStorage cache, then inspect the same account id's React runtime state versus cached quota state. Do not unify WebView/Chrome localStorage or mutate account-card semantics until same-account backend truth is proven inconsistent. A DEV-only diagnostics surface is the preferred first slice for this class of issue.

  • Vendor preset cURL templates that depend on platform cookies should use a neutral placeholder such as {{platformCookie}}. If platformCookie is stored for an account, keep it scoped to management quota/billing curl execution and never use it as runtime auth, route guard identity, or upstream model/chat credential.

  • Management-only credentials such as modelFetchApiKey/modelFetchBaseUrl must stay out of runtime account synthesis, route guard, usage attribution, and APIKeyEntriesJSON; they are only for management actions such as provider model-list fetching.

  • Relay/Codex model catalog refreshes must use modelFetchApiKey/modelFetchBaseUrl for OpenAI-compatible /models fetching when present, with per-field fallback to runtime apiKey/baseUrl only when the management credential field is empty. Token-plan runtime credentials such as tp-* are not valid evidence that /models cannot be populated.

  • Account-list bulk selection actions should render as one sticky workbench toolbar, not as a nested card or dashed sub-section. High-frequency actions can stay inline; secondary actions should collapse into a menu only when measured available width is insufficient, using a small pure layout predicate plus browser scroll checks that prove no top blank band leaks account cards through the sticky area.

  • When simplifying an account detail surface, reduce repeated information before shrinking individual controls. Prefer these orderings:

    1. remove duplicated summary fields that already appear in a dedicated section below
    2. reuse shared primitives such as QuotaBars, compact stat strips, and embedded-label inputs instead of inventing detail-only variants
    3. keep deep-link restoration and detail hash behavior intact while changing layout
    4. lock the new density with focused tests that assert structure, module ordering, and route restoration

  • For account detail surfaces, keep top-of-page runtime summaries limited to live operational signals. Quota, balance, raw auth content, and export/route controls should live in their own sections rather than repeating in the runtime strip.

  • Account detail mutations that change visible account fields must update the local account-list cache by stable account.id immediately after the backend save succeeds, then use ListAccounts only as a final refresh. Do not update only selectedAccount or rely on reload as the sole display source; if ListAccounts fails or is swallowed, reopening detail from a stale card must still show the saved values.

  • Detail modals backed by frame hash state must update their local detail state synchronously when opening or closing before relying on hashchange. If close only clears selectedAccount while the old detail value is still in local state, the hydration effect can reopen the modal and make the close button require two clicks.

2. Feature / Page Boundary

• Pages: frontend/src/pages/* should be route wrappers, not long-lived business implementation files.
• Features: Heavy page assembly, data loading, derived state, and mutation orchestration should live under frontend/src/features/<domain>/.
• Migration Rule:
  • First move the page body into features/<domain>/<Domain>Feature.tsx
  • Then shrink the page file to a thin prop-forwarding wrapper
  • Then split feature internals into components / hooks / model / tests
• Refactor Cadence for Large Features:
  • When a feature is already live and the file is too large, do not jump straight into many tiny components.
  • Preferred reduction order is:
    1. keep the page working and stabilize the page shell + bridge/data loop first
    2. extract heavy view blocks into a dedicated view file
    3. extract copy/text factories and pure constants/helpers
    4. extract focused mutation hooks such as modal/editor flows
    5. extract data-loading hooks such as snapshot / detail
    6. only then consider a final view-state hook for selectors and derived UI state
  • The goal is to turn the main *Feature.tsx into a page controller instead of a second catch-all file.
• Session Management Baseline:
  • For Wails-backed workbench pages like session-management, the stable split target is:
    • *Feature.tsx -> page controller
    • *View.tsx -> business presentation blocks
    • *Copy.ts -> copy factory
    • *Utils.ts -> pure constants/helpers
    • use*Snapshot / use*Detail / use*Mutation -> focused async hooks
  • If the page also has browser-dev fallback data or dev bridge logic, keep that outside the controller and do not mix it back into JSX-heavy files.
• Current Baseline:
  • AccountsPage -> features/accounts/AccountsFeature.tsx
  • StatusPage -> features/status/StatusFeature.tsx
  • SettingsPage -> features/settings/SettingsFeature.tsx

Session Account Affinity & Failure Budget Routing

原则

• Session Account Lease：同一个 Codex session（按 session_id + provider + model_family 识别）在同一账号上失败达到固定次数（默认 2）后才释放 lease 切到下一个账号。
• Soft Quota ≠ Eviction：本地 quota=0 / remaining=0 只是软信号，不驱逐当前 session。Codex 存在"最后一个任务即使额度归零也可继续完成"的行为，直接按 quota=0 切账号会打断尚可完成的任务。
• Hard Failure Budget：仅真实 upstream terminal error（429 usage limit、401 auth invalid、stream closed before completed、websocket 1008 policy violation）累计 session failure budget。
• Disabled Account Immediate Switch：用户禁用账号是明确操作意图，必须立即生效。禁用时清除该账号在所有 session 的 affinity binding + bump pool epoch，当前已 commit 的请求不中断，但下一个请求必须走其他账号。
• Enabled Account Immediate Entry：用户启用账号后，SetRouteDisabled(false) 必须清空该账号的 stale transient route block（Unavailable / NextRetryAfter / ModelStates / Quota / LastError）并 upsert scheduler，使账号无需重启即可参与候选。
• Pool Epoch：任何影响路由候选的操作（启用/禁用/新增/删除/重登/auth file 更新/credential 变更）必须推进全局 epoch，使 session affinity 在下一次请求时感知候选池变化并重新评估 lease。
• Post-Commit Freeze：流式请求在第一个 upstream event 或第一个 downstream write 后 commit，此后同一请求不允许跨账号拼接输出。失败只计入 session failure budget，等下一次请求再重新选。
• Pre-Commit Fallback：OAuth refresh 失败、上游握手失败、首次 bootstrap error 等 pre-commit 错误仍可在同一请求内 fallback 到下一个账号。
• Migration Backups Exclusion：migration-backups/** 目录下的旧 auth 文件永不参与 runtime routing 候选，仅在人工恢复时使用。

实现要点

• SessionAffinitySelector 扩展：FailureBudget（默认2）、RecordRouteFailure、RecordRouteSuccess、BumpPoolEpoch
• SessionCache 扩展：failureCount（同 session+auth 失败计数）、poolEpoch（账号池版本号）
• Manager.conductor 的 Execute/ExecuteCount/ExecuteStream 路径均需在成功/失败时调用 recordSessionRouteSuccess/Failure
• applyAccountStoreStatusChange：禁用时 InvalidateAuth + BumpPoolEpoch，启用时 SetRouteDisabled(false) 清 stale block
• rewriteRouteCandidates：缓存命中但 auth 不在候选池时自动 invalidate 并 fallback，不再卡在 stale binding
• synthesizeAccountStoreAuthFile：过滤 isMigrationBackupAuthFileName
• 配置项（待暴露到 config.yaml）：session_failure_budget: 2, session_failure_window_seconds: 300

3. Relay Service Config Boundary

• Model: Relay service client keys are sidecar top-level api-keys, not upstream provider assets such as codex-api-key.
• Rules:
  • Never use account-pool api-key assets as the Status page relay key source.
  • Status/relay configuration must read and write sidecar api-keys through Wails + management API.
  • Relay key editing may be multi-value; preserve order, trim blanks, and deduplicate exact duplicates.
  • Relay endpoint previews should expose localhost, hostname, and LAN IP forms when available.
  • If relay config is meant for LAN clients, sidecar bind host must not be restricted to 127.0.0.1.
  • “Apply to local Codex” is a local workbench flow, not a sidecar truth editor:
    • provider / model / reasoning effort are local Codex defaults for future sessions
    • provider options should merge the page-local options with existing [model_providers.*] read from ~/.codex/config.toml
    • model options should prefer aggregated account-pool catalogs, and only fall back to ~/.codex/models_cache.json when the aggregated result is empty
  • Writing local Codex config must be preservative:
    • config.toml uses minimal text patch updates for owned keys
    • auth.json uses field-level merge
    • do not rewrite the whole file and destroy user ordering, comments, or unknown fields

3.1 Account Template Local CLI Apply

• Scope: Use this when account cards, vendor presets, or local CLI apply flows map an account template into Codex or Claude Code configuration.
• Entry Rule:
  • Account-card actions are intent launchers only. They may open a confirmation page/modal, but must not write local CLI files before the user confirms.
  • Account detail auth-file/config management modules own their CPA download and local CLI apply actions in the module header. The detail sidebar/nav is navigation-only and must not park 应用到 Codex / 应用到 Claude Code buttons in a footer. The module body must show real generated config data, such as the CPA type: "codex" JSON preview, not explanatory placeholder cards.
  • Only show Codex / Claude Code apply actions for official or verified template targets. Do not infer a Codex button from generic OpenAI-compatible capability alone.
  • DeepSeek is currently treated as a Claude Code-only official template target; do not show a Codex action unless a later verified template explicitly enables it.
• Mapping Boundary:
  • Keep template resolution in pure model code under frontend/src/features/accounts/model/, not inside AccountCard.
  • A single account has a fixed application mode from its source: Codex API key accounts use API key mode; Codex OAuth/auth-file accounts use OAuth mode. Do not offer an API key/OAuth toggle inside the confirmation page for one account.
  • Codex API key mode must write the currently selected account asset (AccountRecord.apiKey plus the matched source format base URL), not the GetTokens relay key or relay endpoint. Missing relay keys must not disable this path.
  • Claude Code local apply normally writes the GetTokens relay key and relay endpoint. Do not reuse the Codex API key direct-write rule for Claude Code unless a verified direct-upstream mode is explicitly designed.
  • DeepSeek, Kimi, MiniMax, Doubao, StepFun, Xiaomi MiMo API / Token Plan, and Zhipu GLM Coding Plan are verified Claude Code direct-upstream exceptions: write the selected account API Key, formatBaseUrls.anthropic, and ANTHROPIC_AUTH_TOKEN according to their official Claude Code guides. Do not replace that URL with the local GetTokens relay endpoint. Zhipu and MiniMax should also write the official API_TIMEOUT_MS=3000000.
  • When a Codex API key account is passed through ApplyRelayServiceConfigToLocalV2, mark it so relay key metadata is not updated; account-pool secrets must not be recorded as relay service key last-used metadata.
  • Codex provider id should default to the user's current root model_provider; avoid forcing a stable provider id such as gettokens because existing Codex sessions may depend on the current provider.
• Confirmation UI:
  • Use a file-preview layout: left side target file list, right side selected file diff.
  • Avoid explanatory card stacks inside the modal. Keep summary metadata compact and make the file diff the primary content.
  • Modal height should stay stable when switching files; file tabs/list selection must not resize the shell.
• Codex auth.json Semantics:
  • API key mode writes the minimal Codex auth payload: auth_mode=apikey plus OPENAI_API_KEY. Clear OAuth tokens, flat token fields, refresh metadata, agent identity, and user metadata.
  • OAuth/auth-file mode writes auth_mode=chatgpt plus native nested tokens. If the source auth-file is sidecar-normalized into flat access_token / id_token / refresh_token fields, convert it back to Codex native nested tokens before writing.
  • Codex auth detection follows source behavior: explicit auth_mode wins; only when it is missing should OPENAI_API_KEY cause API key fallback.
  • For OAuth mode, provider config must not leave env_key or experimental_bearer_token values that would make Codex choose API key / relay token auth instead of ChatGPT OAuth.
• Claude Code Settings Semantics:
  • Only patch controlled env keys such as ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, and model family fields.
  • Preserve unrelated settings such as permissions, hooks, status line, MCP, and unknown fields.
• Rendering Rule:
  • Account groups should render available local data first. Do not block the full account list on slower per-account enrichment; update enrichment-dependent fields incrementally.
  • Account-list cold start should seed first paint from the sidecar-owned account-store SQLite snapshot through Wails before sidecar readiness; browser localStorage is only a secondary remount/preview cache. ListAccounts() must still overwrite the snapshot after sidecar readiness. First-paint snapshots must exclude credentials and raw auth material such as apiKey/apiKeys, headers, cookies, cURL scripts, modelFetchApiKey, and rawAuthFile.
  • Sidecar management /accounts may degrade to a card-only account-store snapshot when credential attachment fails, so the UI can leave skeleton and show local account assets. Runtime account synthesis must remain strict and must not route requests with card-only or missing credential records.
  • Whole-page account skeletons should only block when no account rows are available. A not-ready sidecar may disable actions, but it must not hide cached account cards; filter-empty states must render as filtered empty UI, not as loading skeletons.
  • Runtime quota sync must separate batch reads from active refresh writes:
    • account-card percentage quota bars must always display remainingPercent as remaining quota. Provider-specific payloads that report usage percent (for example Xiaomi MiMo token plan) must be normalized to remaining quota before reaching the card UI; do not add provider-specific "used percent" branches in QuotaBars.
    • page entry, visibility restore, interval sync, and global "refresh runtime" actions read sidecar runtime snapshots through GetQuotaStatuses(accountKeys) / /v0/management/gettokens/quota-status?account_keys=... when the target keys are known, with GetAllQuotaStatuses retained only as compatibility fallback; they must not loop over account cards and call single-account GetCodexQuota
    • when the known target account_keys set can be hundreds or thousands of rows, the frontend/Wails caller must chunk GetQuotaStatuses(accountKeys) into bounded requests before crossing the management API. Do not send the full account pool in one GET query, because WebKit/Wails marshalling, sidecar parsing, and Gin request logging all amplify the payload.
    • sidecar access/request logging must summarize account_key and account_keys query values instead of writing raw account identifiers. Keep the parameter name and a bounded count such as [redacted:200]; do not log full acct_* lists from quota-status or account bulk endpoints.
    • AccountsFeature must consume runtimeRefreshing / refreshAccountsRuntime from useAccountsPageStateContext; do not define a page-local refreshAccountsRuntime that shadows the hook and calls refreshAccountQuotasBatch(accounts) from the global header action
    • sidecar quota-status batch reads must return ordered items, include stale empty states for missing requested keys, and keep the single account_key response shape compatible for old callers
    • user-intent active refresh for multiple selected accounts should use the batch job flow first: StartCodexQuotasBatchRefreshJob / POST /v0/management/gettokens/quota-refresh-batch/jobs, then poll GetCodexQuotaBatchRefreshJob / GET /v0/management/gettokens/quota-refresh-batch/jobs/:job_id; the old synchronous RefreshCodexQuotasBatch path is compatibility fallback only
    • batch quota refresh jobs should deduplicate account_keys, return immediate job_id, expose pending/running/succeeded/failed plus per-account items/errors, and make restart semantics explicit as in-memory runtime state
    • background quota refresh jobs must be tied to account and sidecar lifecycles: each job needs a cancelable context, account deletion must cancel matching pending/running jobs, sidecar shutdown must cancel all pending/running jobs, and workers must re-check account existence before each outbound quota request
    • single-card refresh may keep using single-account refresh, but list-level and selected-bulk paths must not emit one Wails/management request per account
    • account-card footer refresh is a runtime sync action, not only a quota-script action. Cards without quota/billing curl support, such as OpenAI-compatible providers with only usage attribution, should still expose a per-card runtime sync affordance and label it as runtime sync instead of hiding the button.
    • when batch refresh partially fails, keep successful quota items, mark failed targets stale/degraded, and preserve existing quota windows where possible
  • Account-list bulk mutations must be real batch operations:
    • Auth-file imports that already arrive at Wails as a batch, such as UploadAuthFiles, must call a sidecar batch-create endpoint and trigger account-store apply once. Do not loop over hundreds of auth files and call single-account management create unless the new batch route is missing on an old sidecar and the Wails boundary is deliberately using a compatibility fallback.
    • Repeated auth-file imports must deduplicate by normalized credential identity inside sidecar/accountstore, not by frontend state or upload file name. Compute dedupe keys after NormalizeAuthFileForSidecar; do not use account_id alone because K12/organization auth files can share it across many real accounts. Persist only hashed identity material and return created/skipped/error summaries from batch-create.
    • Auth-file import preflight must be sidecar/accountstore-owned and reuse the same batch planning logic as create. Frontend or Wails may display wouldCreate/skipped/failed, but they must not reimplement DB duplicate decisions from file name, email, or account_id. Preview endpoints are read-only and must not trigger account-store apply; old sidecars should return a supported=false style fallback so actual upload can still proceed.
    • After a large account import succeeds, reload account inventory with refreshSupplementalData: false. Do not make import completion wait for quota, usage, or rate-limit supplemental runtime sync; those should run through explicit "refresh runtime" actions or background snapshot sync.
    • Account import file picker paths must batch multi-file selections before calling readUploadFiles. AntD Upload.beforeUpload fires per file, so aggregate files through a pending queue/microtask instead of parsing and appending queue state once per selected file.
    • Import queue footer and submit state should derive selected counts, validity, and selected payloads from one shared model summarizer. Avoid separate filter/reduce/every scans over hundreds of queued items on every render.
    • selected bulk delete uses DeleteAccountsBatch / POST /v0/management/accounts/batch-delete with unified acct_* account ids, not a frontend loop over executeDeleteAccount
    • when a new sidecar management endpoint is introduced on an existing hot account path, keep a Wails/root compatibility fallback for release bundles that may still carry the previous sidecar; a missing route 404 on the new endpoint should downgrade at the management boundary instead of surfacing a hard UI failure
    • batch mutation handlers should deduplicate keys, return per-account success/error summaries, and trigger expensive follow-up work such as account-store apply or list reload once per batch
    • single-card delete/status paths may keep their focused single-account APIs; selected-bulk paths must not emit one Wails/management request per selected account
    • group-level account actions such as "enable group", "disable group", and "delete group" are account-list bulk mutations too. They must reuse the same batch bridge as selected bulk actions and must not loop through card-level handlers from the group menu.
    • bulk enable/disable must use a Wails batch bridge such as SetAccountsDisabledBatch and prefer a sidecar batch status route. A single-account PATCH loop is allowed only as a Wails/root compatibility fallback when an older sidecar returns 404 for the batch route; the frontend must still issue one batch call.
  • Account-list large-scale rendering must stay windowed:
    • 1600+ account previews must not render one data-account-card DOM node per account
    • layout changes to AccountGroupSectionView / accountListLayout must preserve virtual window behavior across search, grouping, selection, detail hash restoration, and internal scroll
    • The selectable/card grid must not also be the virtual spacer container. Keep #account-group-body-* / [data-plan-group-grid] limited to visible cards, put top/bottom virtual spacers in an outer wrapper that owns data-account-group-virtualized and render-window metadata, and mark spacers pointer-events: none plus user-select: none so browser comments, hit testing, and copy selection do not target the hidden scroll range as if cards failed to load.
    • virtual spacer height must be derived from measured rendered row stride when cards are present; fixed row-height estimates are only first-render/fallback values, because overestimated rows create visible blank space and oversized scroll ranges
    • scroll-driven virtual window state must not recompute group-wide action availability, selection status, quota refresh eligibility, disable eligibility, or delete eligibility on every scroll frame; derive those aggregates in a model helper and memoize them by group.accounts plus selection state
    • acceptance for large-list UI work should run docs-linhay/scripts/accounts-scale-browser-check.mjs or an equivalent headless scale check that records total accounts, rendered card count, scrolled virtual window, spacer-to-measured-row ratio, internal scroll position, and screenshots under the matching space

3.2 Codex Workspace & Local Config Surfaces

• Codex Binary: For Codex CLI binary version/source management, use the dedicated gettokens-codex-binary-management skill. Keep it as an independent binary-management business; do not merge it into account pool, local apply, usage, session, or routing flows.

• Codex Account List / Channel Routing: For Codex account request order, route probing, OAuth/auth-file model aliasing, openai-compatible model mappings, channel route mode, and #frame=codex&workspace=account-list, use the dedicated gettokens-codex-account-list skill. In the Account Routing Engine rollout, Codex account list is the Codex Channel Routing workspace: channel order, route mode, channel group state, dry-run/explain, and probe are Codex-owned channel config, not global account inventory priority. Current channel route mode is two-mode only: sequential / balanced; project, projectBindings, projectModeFallbackRouteMode, fallbackMode, and upstream compat route modes such as weighted / canary are removed from Channel Routing save/execute/UI paths.

• Project Account Candidate Pool Rule: A project-fixed-account requirement is an account candidate pool rule, not a project route mode, project scope model, or projectBindings revival. Model it as projectKey + channel + allowAccountIDs + enabled, put stable ProjectKey / ProjectName / ProjectKeySource / ProjectKeyConfidence on sidecar RouteContext, compile enabled rules into CompiledRouteSnapshot, execute them in PolicyStagePoolScope with strict allow semantics, and emit DecisionTrace / explain steps from the route engine. Project matching is exact match only: projectName is display/audit only, projectKey must be source-prefixed, current Codex first-pass key is workspace:<sha256(normalized_abs_path)>, no key or ambiguous multi-workspace means not evaluated and no fail-closed, and duplicate enabled matches fail closed as rule conflict. Existing P2 RequestPolicy, P3 StickyPolicy, and sequential / balanced selection must operate only inside the narrowed pool. If the allow set contains no routeable accounts after hard filters, fail closed instead of falling back to the channel pool. Rule changes must bump route snapshot / pool epoch so sticky is re-evaluated on the next request. Writable projectBindings paths must remain deleted; historical input may only be dropped or migrated.

• Channel Routing Source of Truth: For Codex / Claude runtime routing, ~/.config/gettokens-data/channel-routing/config.json is the main decision source. Treat sidecar routing.strategy in ~/.config/gettokens/config.yaml as legacy relay/config compatibility only; it must not drive Codex / Claude candidate ordering once channel routing is configured. The CLIProxyAPI fork should install GetTokens channel routing as a pool-scope route policy before legacy selectors, and balanced mode should read active-session counts from the live-session tracker instead of a display snapshot.

• Channel Routing Runtime State Persistence: Account-list probe / refresh state and real request routing must share the same sidecar-owned runtime state, not split between Wails explain state and in-memory route guard state. Persist transient abnormal account sources such as auth-error, quota-empty, rate-limit, cooldown, model-unavailable, and upstream-error in the profile-local channel-routing/config.json.runtimeStates, make account-route-guard consume those states on the real request hard-filter path, and write route guard updates back to the same file when they can be mapped to a stable account identity such as acct_*.

  • manual-disabled is not a persisted runtime-state fact. User disable/enable truth comes from the account-store SQLite / management account status and synthesized runtime auth. Wails explain/probe and sidecar route guard must ignore legacy persisted runtimeStates.*.sources.manual-disabled; any channel-routing save should prune it while preserving other sources on the same account.
  • Runtime state cleanup is source-scoped. Clearing auth-error or a legacy manual-disabled entry for one account must not delete another active source such as rate-limit on the same account.
  • When the sidecar writes shared channel-routing JSON, preserve Wails-owned or future channel fields as raw JSON where the sidecar only needs a narrow routing view. Tests should lock that channels, events, nextEventID, and runtimeStates survive route guard persistence.
  • For request-result blocks, prefer stable acct_* account keys over transient auth-id:<id> when available, so restart recovery and account-list state can address the same asset.
  • Sidecar restart recovery must hydrate persisted runtimeStates back into AccountRouteGuardStore before management quota/status reads. The real request hard-filter path and /v0/management/gettokens/quota-status?account_keys=... must report the same active blocked/sources facts after restart; do not make account cards depend only on in-memory route guard state while routing separately reads persisted blocks.
  • OAuth auto-refresh terminal credential failures must enter the same route guard persistence path as request-result failures. When Manager.refreshAuth() records an unauthorized / invalid_refresh_token / refresh_token_reused / refresh_token_invalidated / relogin-required failure on an auth, it must notify auth update hooks, and GetTokens' route guard hook must convert that auth state into account-scoped auth-error. Otherwise restart or startup refresh can prove a whole account group is unusable while account cards still show only the few accounts that previously had persisted quota/runtime errors.
  • Auth-file OAuth auth-error route guard lookup must include stable provider account identity, not only the individual GetTokens acct_* key. If multiple account-card assets share the same OpenAI / ChatGPT auth_json.account_id, a terminal credential failure observed on one asset must block sibling assets by an identity lookup key such as openai-account-id:<id> in both real route filtering and management quota-status. Do not fan out hundreds of duplicate persisted runtimeStates just to make cards red; index the guard by provider identity and dedupe repeated sources in quota-status presentation.

• Codex Extensions: For Codex Skills / MCP Servers, [[skills.config]], tk://github.com / tk://gitlab.com skill sources, and #frame=codex&workspace=skills|mcp-servers, use the dedicated gettokens-codex-extensions-management skill. Keep source-accurate parsing, modal/list UI semantics, and cleanup split rules in that skill instead of expanding this general domain skill.

• Claude Code Workspace Parity: When Claude Code adds a capability that corresponds to existing Codex workspace entries, keep the workspace granularity aligned with Codex unless Claude semantics clearly require a different information architecture.

  • If Codex exposes separate workspaces such as #frame=codex&workspace=skills and #frame=codex&workspace=mcp-servers, Claude should expose separate workspaces such as #frame=claude&workspace=skills and #frame=claude&workspace=mcp-servers, not a single merged page with internal tabs.
  • Claude skills read-only scanning must include both native Claude roots ($CLAUDE_CONFIG_DIR/skills or ~/.claude/skills, plus project .claude/skills) and unified Agent Skills roots (~/.agents/skills, plus project .agents/skills). GetTokens installs project skills under .agents/skills, so scanning only .claude/skills produces a false empty state.
  • Implement this split as route-level feature components, for example ClaudeCodeSkillsWorkspace and ClaudeCodeMcpServersWorkspace, with the page wrapper only dispatching by ClaudeWorkspace.
  • Shared shells and visual primitives are still encouraged. Reuse AssetWorkbenchShell, preview data, DTO mappers, and list patterns where they fit, but do not let shared UI collapse distinct navigation surfaces into one tabbed page.
  • Keep legacy hash/storage compatibility explicit. A retired merged workspace such as extensions may migrate to the safest default (skills), but should not remain a first-class menu item once split pages exist.
  • Page-internal segmented controls should represent local field choices such as MCP transport, filters, or modes; they should not be used as replacement navigation for top-level or second-level workspaces that already exist in the sidebar.

• Usage Desk Local Projection:

  • Treat local file projection as a provider-specific data source, not a generic Codex-only feature. Each provider needs its own backend reader, runtime cache, progress events, root Wails binding, generated frontend binding, preview payload, and frontend source switching.
  • Claude Code local usage projection reads CLAUDE_CONFIG_DIR || ~/.claude under projects/**/*.jsonl only. It is read-only: never write, delete, compress, rename, or rewrite Claude native session files.
  • Claude Code projection must skip subagents/agent-* sidechain files and parse only assistant envelopes with message.usage; do not return prompt text, tool input, message body, credentials, emails, or raw content.
  • For streaming Claude Code assistant rows, dedupe by message.id. Keep the final row with non-empty message.stop_reason; if multiple comparable rows exist, keep the one with the larger output_tokens. Skip unfinished rows with empty stop_reason or output_tokens=0.
  • Token mapping is input_tokens + cache_creation_input_tokens, cache_read_input_tokens || cached_input_tokens, and output_tokens.
  • Frontend Usage Desk rendering must branch by source === 'observed' vs source === 'projected', not by workspace. A workspace-specific override such as workspace === 'claude' inside the observed branch can make a projected button visually selected while still rendering observed data.
  • usage-local:* events must carry and filter provider, so Codex rollout projection and Claude session projection do not overwrite each other's page state.
  • Verification for this class of change must include fixture tests, generated binding assertions, preview projected rows, and a real local-file sanity check that reports counts/totals without reading or printing sensitive message content.

• Session Management Local Files:

  • Treat ~/.codex/sessions, ~/.codex/archived_sessions, and ~/.claude/projects as potentially multi-GB local stores. Never make page entry depend on synchronous full-file parsing when a bounded snapshot or stale cache can satisfy the first paint.
  • In Wails runtime, session-management first paint should rely on Wails/backend snapshot caches rather than duplicating the full snapshot in WebView localStorage. Browser preview may keep a localStorage snapshot cache, but desktop mode should disable that cache and best-effort remove legacy gettokens.sessionManagement.snapshot* keys to avoid WebKit WAL and heap pressure.
  • Snapshot/list APIs should return summaries only. Do not carry full message bodies, raw tool payloads, or per-message content through snapshot DTOs.
  • Detail APIs used by the UI must be payload-bounded. Keep full parsing inside backend-only analysis paths when needed, but UI detail responses should prefer summary rows, cap message count, and avoid returning full content unless a scoped requirement explicitly needs it.
  • Batch/session analysis over all projects or selected sessions must stream per-file aggregation. Do not call full detail/message collection for every target session before analysis; collect metadata separately, then read JSONL rows into bounded counters or explicit worker-budgeted accumulators.
  • If the UI needs full session-detail visibility, split metadata from messages. Get*SessionDetail should return only metadata/counts, while a separate message-page API reads JSONL line windows (offset / limit) and stops after the current page plus one lookahead row for hasMore. Frontend detail views should append pages on demand and render only the loaded window.
  • Session list panels over local stores must be DOM-windowed once they can render hundreds or thousands of rows. Do not map every session row from the active project into WebKit; render only the visible window plus overscan and preserve scroll height with spacer padding.
  • Frontend detail state must also have an explicit retained-message cap, independent of backend pagination. Loading more pages should advance the backend offset / hasMore cursor but keep only the newest retained message window in React state, so a multi-GB local session store cannot grow WebKit heap without bound.
  • Raw JSONL inspection must be per-message and on demand. Message-page DTOs may carry a source lineNumber, but raw JSON should be fetched through a separate line-read API only after explicit user interaction, never bundled into list/detail/page payloads.
  • Frontend raw JSON caches must be bounded, preferably by LRU entry count plus byte limit if raw rows can be large. Opening many raw rows in one detail modal must evict older entries instead of accumulating a per-message object forever.
  • Any in-process cache for session details must have both entry-count and approximate-byte limits. Oversized details should use disk cache only, not stay resident in App.
  • Disk caches must invalidate by file fingerprint such as size plus mtime. Do not use session id alone as a cache key for mutable JSONL files.
  • Regression coverage for this class should include cache hit, stale-cache invalidation, payload compaction, memory-bound eviction, and at least one live benchmark path gated by an explicit environment variable so CI never reads a developer's real sessions.

• Codex Live Sessions: For #frame=codex&workspace=live-sessions, treat the feature as runtime observability, not local session-file management. Use this when surfacing in-flight request/session state from CLIProxyAPI.

  • Data ownership starts in the CLIProxyAPI fork. Add an in-memory runtime tracker and a read-only management endpoint first; then expose it through internal/wailsapp, root main.App, generated frontend/wailsjs, and finally the React feature.
  • Keep the UI read-only. Do not add request cancel, replay, forced WebSocket recovery, or full payload display unless a later requirement explicitly scopes the action and safety model.
  • Default list rows should stay low-noise. Show only the operator-facing identity pair requested for the feed: project name plus account / http|ws, with the session id as a right-aligned secondary action. Keep status, model, timing, request ids, execution ids, and redacted diagnostics in detail panes.
  • If a feed row exposes session-id copy, make it an independent click target that stops row-selection propagation. A successful click must provide visible feedback such as 已复制 / Copied rather than relying on a title change or silent clipboard write.
  • Timeline rows inside the detail pane should still be scan-friendly. Compress each row to one line, prefer short request ids / short clock times, and surface only the core timing metrics first (total, TTFT, first token). Treat secondary gap / stream metrics as secondary-width affordances, not as mandatory first-line content.
  • The detail shell and filter shell are workbench surfaces, not nested cards. Avoid stacking a second border + shadow card around the timeline, the filter bar, or the detail root unless a later design system rule explicitly requires that shell.
  • Long live-session detail panes should scroll inside the detail column, not by growing the whole workbench page. On wide layouts, keep the detail column sticky, cap it to the viewport, use overflow-y-auto, and set overscroll containment so chart/timeline inspection does not roll the page header away.
  • projectName is a display label owned by the CLIProxyAPI live tracker. The sidecar may enrich it from trusted local Codex session metadata (CODEX_HOME || ~/.codex session JSONL) before returning the live snapshot; GetTokens should only pass the optional DTO field through Wails/root bindings/frontend model and fall back to an explicit unknown-project label when absent. Do not add Wails/frontend compatibility lookup for old sidecars unless a later requirement explicitly reintroduces compatibility.
  • Account resource surfaces inside live-session details should reuse accounts-domain components such as QuotaBars and BillingBalance. Add a small adapter from live request quota / billing DTOs into account display shapes instead of copying quota or balance JSX into live sessions.
  • Never display raw request/response payloads, credentials, bearer tokens, cookies, or unredacted error bodies. Diagnostic copy must be redacted and bounded.
  • When correlating WebSocket and HTTP usage, preserve request ids through context. Usage hooks should update an existing WebSocket request when the request id is known, not create a duplicate HTTP-only session.
  • Live-session timing must consume the same telemetry source as usage attribution. When usage.Record carries Latency or TTFT, map those into LiveTimingMetrics (totalDurationMs, firstEventMs, firstTokenMs) and derive streamDurationMs from them; do not rely only on live tracker wall-clock deltas or token detail. A visible request row without positive timing values is expected to produce an empty timing chart, so backend timing propagation is the primary fix point.
  • When trimming live-session memory, distinguish realtime snapshot retention from historical retention. The in-memory tracker may cap session/request maps for RSS control, but historical request data must be written to a disk-backed ledger before it can be trimmed from memory.
  • Snapshot cleanup endpoints such as DELETE /v0/management/gettokens/live-sessions clear only realtime memory state by default. Disk history cleanup requires a separately scoped API with explicit filters/retention semantics; do not reuse memory prune to delete history.
  • Live-session history endpoints should be paginated from disk (limit / offset / window / session_id) and must not rebuild the old unbounded in-memory details list.
  • Frontend live-session history state must also be explicitly bounded. Overview/detail "load more history" may page from disk, but React state should retain only a fixed request window and disable further load-more at that frontend cap instead of accumulating historical request objects in WebKit heap.
  • Treat Codex upstream HTTP fallback as an observable sticky state. GetTokens may infer and explain the fallback, but must not promise transparent recovery to WebSocket after Codex has already downgraded.
  • The frontend must support browser preview with mock snapshots, while desktop mode polls the real Wails snapshot. Show source state such as live, cache, or preview so stale sidecar state is not mistaken for no sessions.
  • Live-session refresh should use structural snapshot merging instead of replacing the whole React snapshot on every poll. Ignore clock-only changes such as generatedAt, preview/cache timestamps, active session duration, and active request streaming duration when the underlying sessions/requests did not change. Reuse unchanged session and request object references so the feed, selection, and detail pane do not flicker during polling.
  • Browser preview/cache detail polling should not rewrite detail state every second just to advance time. Let charts project the current active request through explicit nowMs model options, and keep detail/history state updates for real structural changes.
  • Request timing trend charts must be driven by request records, not decorative UI state. Put trend derivation in a pure model under features/codex-live-sessions/model/, merge the active request by requestID, sort points by startedAt, and accept an explicit nowMs option so live requests can be projected in tests.
  • For streaming / active / reconnecting requests without completedAt, project totalDurationMs from nowMs - startedAt with a bounded safety cap. Do not mutate the original request or invent first-event / first-token timings.
  • Only the current active request is allowed to use nowMs - startedAt projection in the timing trend. Historical request rows that still carry streaming / reconnecting from cache or stale sidecar state must keep their recorded timing.totalDurationMs or completedAt - startedAt; otherwise every total-duration point will grow together.
  • Live request sequence is a sidecar-owned lifecycle counter inside one Codex conversation/session. Memory retention may cap the retained request map, but pruning must only delete old requests; it must not renumber retained requests back to 1..50. When a long session keeps only 50 requests, the first retained request may legitimately be #6 and the newest #55.
  • Trend chart x positions should read as request sequence, not timestamp spacing. Keep request records sorted by startedAt, then render the visible slice as dense equal-step bars with #sequence as the x-axis label; do not stretch sparse requests across real elapsed gaps.
  • Trend chart data window is a fixed count cap, not a fixed time window. Keep only the latest capped request points for the chart model, so new requests push the sequence labels forward (#50 -> #51 -> #52) while the visible data volume remains bounded.
  • Trend chart viewport should be a fixed, non-scrollable audio waveform chart. The visible request count is width-driven: wider surfaces show more recent request bars, narrower surfaces show fewer, and the latest request stays anchored near the right edge. Do not reintroduce horizontal panning or auto-scroll follow logic.
  • The timing metric picker below the chart summarizes the same trend window. Show average values for total / TTFT / first token / stream / queue / auth select / connect / gaps / rates rather than echoing the latest single request; keep latest-request values in the timeline rows and chart footer.
  • The timing metric picker should prefer the sidecar session-level timingSummary when present. Treat timingSummary.window=retained_requests as the authoritative average window, show sampleCount plus sequenceFrom / sequenceTo, and mark the UI as Sidecar summary. Only use frontend request-window averaging as a fallback for old sidecars or preview data without summary, and label that path as a local estimate.
  • Sidecar timingSummary must not let stale historical streaming/reconnecting requests grow on every snapshot. Only the current active request may project totalDurationMs from the sidecar summary generation time; first-event and first-token fields must remain absent until observed.
  • Keep the live-session chart visually inside the page section, not as a nested card. Use the existing Swiss-industrial chart tokens, footer summaries below the graph, and live markers such as dashed strokes/rings for in-flight samples.
  • Request timing trend visuals should read like a forward-moving audio waveform, not a finance line, ECG trace, or candlestick chart. Render exactly one centered vertical amplitude bar per request for the selected timing metric; longer durations produce taller bars, and live rings distinguish in-flight samples.
  • Timing trend motion should not redraw the full waveform on every live refresh. Keep bars steady; use a short opacity settle only when switching metrics and a subtle breathing ring on the live sample to indicate activity.
  • The request timeline inside the detail pane is a recent-scan surface, not the full history list. Render only the latest 15 sorted request rows and keep the visible row count aligned with that cap; rely on history/detail data for deeper inspection.
  • Browser preview data for timing charts must include multiple completed requests plus one in-flight request, so #frame=codex&workspace=live-sessions exercises curve shape, latest sample footer, and live marker behavior without a Wails runtime. For layout/density bugs, synthesize the edge cardinality that caused the issue, such as 50 retained requests with the latest live request at #50; do not accept a 3-5 request preview as proof for long-session chart fixes.
  • Browser preview timing data must behave like real request history, not like a decorative animation. Completed preview requests should derive timings from stable request identity such as sequence, not from the current visible-window index, so the same request keeps the same timing values across refreshes and rolling-window shifts.
  • Preview live samples may update only the active/latest request. Keep completed bars stable across consecutive preview refreshes, include occasional completed slow-request spikes to keep the chart scale realistic, and verify in browser/DOM that after a short wait only the live sample geometry changes.
  • Do not let preview live elapsed duration become the chart's moving maximum every second. If live growth changes the global chart scale, all historical waveform bars appear to move, which violates the "steady bars + subtle live ring" contract.
  • Regression coverage for this class should include pure trend model tests, source-structure tests for live refresh / request-sequence bar x-axis, preview multi-sample or edge-cardinality assertions, typecheck, build, focused model.test.mjs, and at least one browser/DevTools DOM or screenshot check that the chart renders nonblank and has no label overflow, x-axis label overlap, or live-ring clipping.
  • On structural snapshot merge for live sessions, treat source=live sidecar polls as authoritative. If the next live snapshot omits a session, remove it from the feed instead of retaining stale browser state, because the omission may reflect sidecar-side account pruning or runtime availability filtering. Retention of prior rows is only valid for explicit cache/failure states such as source=cache, not for normal live polling.
  • If account deletion, detachment, or disablement should make a live session disappear, fix that at the sidecar runtime boundary first. RuntimeAccountProjection and the live-session tracker must agree: account mutations should prune or suppress the matching tracker rows by authID / accountKey, while the frontend only mirrors the authoritative live snapshot and must not recreate omitted rows locally.
  • The feed header supports a clickable dual-mode switch: session navigation (by project + account) and request rollup (by embedded requests + row-only activeRequestID). Request rollup aggregates all retained requests across sessions, sorted by startedAt, with each row showing short request ID, protocol, project, model, account, timing summary, status badge, and sequence number.

• Account Route Guard & WebSocket Hot Switch:

  • Route selection is not payload shaping. For same-schema upstream requests, preserve client payload fields by default and only apply narrowly necessary mutations such as resolved model normalization, auth/connection headers, internal transport flags, explicit payload config rules, or cross-account transcript replay cleanup. Strategy routing must answer "which account handles this request", not silently remove fields like previous_response_id, prompt_cache_retention, safety_identifier, stream_options, metadata, or unknown future Responses fields.
  • Treat manual disable and automatic rate-limit blocking as the same routing-domain condition: an account must not participate in new candidate selection.
  • Use AccountRouteGuardStore source aggregation for in-memory guard state. Keep sources independent, such as manual-disabled and rate-limit, so automatic recovery never clears a user manual disable inside the current process; do not persist manual-disabled to shared runtimeStates.
  • Rate-limit rule writes are account-card scoped. New rules must use acct_* account_key; legacy keys such as auth-file:*, codex-api-key:*, and openai-compatible:* are migration/history inputs, not new rate-limit binding keys.
  • Rate-limit management writes must not return success until runtime guard evaluation has completed. If the post-write evaluation fails and no explicit degraded/stale DTO is designed, roll back the just-written DB change and return a visible error rather than leaving hidden side effects.
  • Serialize full and account-scoped rate-limit evaluations. A periodic reconcile must not race with a usage-triggered account refresh and later write stale rate-limit guard state back over newer decisions.
  • Keep SQLite event persistence out of evaluator state locks. Refresh in-memory evaluator state and route guard first, then persist block events so route/status reads are not blocked by event I/O.
  • Request-window rate-limit is an admission problem, not a Gin middleware problem. Reserve only after a single auth has been selected and before executing the request; if reservation fails, deny that auth for the current request and let selector/retry fallback.
  • Request-window reservation usage must count both completed usage events and active pending / committed reservations. Success commits the reservation until usage attribution releases it by request_id + account_key; failure/cancel releases it, and reconcile expires orphan reservations.
  • When moving admission later than selection, preserve retry loop semantics: auths with no executable model still must be marked tried, otherwise alias/model-pool fallbacks can repeatedly select the same unusable auth.
  • Codex API key manual disable must survive every durable layer: GetTokens account-store SQLite -> management account status/config payload -> CLIProxyAPI synthesized runtime auth Disabled=true / StatusDisabled. manual-disabled may exist as an in-memory route-guard source for immediate current-process exclusion, but it must not become a persisted runtimeStates source.
  • Enforce guard state through RoutePolicy deny decisions on the hot path. Do not add Gin middleware that returns 429 in the middle of a request when selector fallback can route to another account.
  • Route-policy explain must include active guard source details, not only a generic account-route-guard reason. A filtered route trace should let operators distinguish manual-disabled, rate-limit, auth-error, upstream-rate-limit, and upstream-error.
  • Quota exhaustion is a route-guard source, not a frontend-only account-card filter. Fresh sidecar quota runtime with remaining <= 0 and a future reset time should write quota-empty into AccountRouteGuardStore; stale/degraded/unknown quota must not create a new hard block.
  • Upstream usage_limit_reached is quota exhaustion / cooldown evidence, not an install error or a relogin-required auth failure. Account cards should label it as usage-limit reached, summarize the upstream payload into user-readable quota/reset copy, and suppress reauth CTAs for that state while keeping raw diagnostics available in detail/copy surfaces when needed.
  • Account-card quota-empty badges must be source-specific. Do not treat generic quota runtime blocked=true as "额度已空"; render the empty-quota badge only when sources[].source == quota-empty or the sidecar blockReason explicitly says quota empty/exhausted. manual-disabled, rate-limit, auth errors, and other guard sources need their own labels and must not override fresh positive quota windows.
  • UI quota display and route quota filtering must share sidecar quota runtime data. Codex API key quota refresh must call sidecar-native POST /v0/management/gettokens/quota-refresh/:account_key; Wails/root must not infer blocked from local quota bars or bridge API key quota by manually writing quota-status.
  • Codex API key quota/billing curl parsing, provider-specific response mapping, HTTP execution, and fresh quota-status upsert are sidecar-owned. Wails/root should only call quota-refresh, quota-test, or billing-test and map the returned QuotaRuntimeState; auth-file usage refresh may still use management /api-call for token injection before writing quota runtime.
  • Provider quota/billing parser fixes must cover both parser layers: main repo internal/accounts fallback parser and CLIProxyAPI sidecar management/quota_refresh parser. Use provider fixture payloads, not live secrets, for tests. If an upstream uses fractional ratios such as 0.53 for percent, normalize 0..1 to 0..100; if a balance endpoint returns nested data.balance shapes, map total/granted/topped-up/currency into the unified billing DTO without adding frontend vendor branches.
  • Runtime acceptance for provider quota/billing fixes should use a temporary fixture server, temporary account-store DB, temporary sidecar port, and quota-refresh with include_billing=true. Verify the returned windows and billing.balance_infos; do not store user-provided cookies or replay production credentials in committed fixtures or logs.
  • Account store schema and metadata initialization must stay out of read/request hot paths. Initialize accounts-v1.sqlite once per sidecar handler/store lifecycle, reuse the initialized store, and use WAL plus bounded connection pools before considering larger read/write separation.
  • Auth synthesis and token persistence must not open accounts-v1.sqlite inside per-file, per-auth, or concurrent refresh loops. Share account-store reads through the current SynthesisContext, serialize Watcher.RefreshAuthState, and keep token-store writes on a lifecycle-scoped cached store with a mutex.
  • Codex OAuth token refresh errors that prove the session is terminal (invalid_refresh_token, refresh_token_reused, app_session_terminated, invalid_grant, token_invalidated, "Could not validate your refresh token", "session has ended", "please try signing in again", "please log in again") are reauth-required states, not transient refresh failures. Do not retry them three times or leave them on the auto-refresh schedule. A later successful refresh or credential update/relogin must reset LastError, Unavailable, NextRefreshAfter, stale model states, and quota/runtime cooldown inherited from the old credential. Do not classify workspace, quota, rate-limit, network, 5xx, or generic refresh_failed states as relogin-required without explicit credential invalidation evidence.
  • If a Codex API key quota refresh fails and Wails falls back to cached quota-status, mark the returned DTO as stale with the refresh error in degradedReason; never make stale cache look like a fresh success on account cards.
  • Auth-file OAuth usage refresh that receives upstream non-2xx, especially ChatGPT terminal failures such as 401 token_invalidated or 402 detail.code=deactivated_workspace, must write stale/degraded quota runtime with the upstream message/code in degradedReason. Parse detail.message/detail.code/detail.type in addition to message/code/error.*; do not hide these cases as a silent cache fallback. Account cards and detail quota sections must surface stale/degraded quota runtime reasons.
  • Terminal OAuth credential invalidation is both a display failure and a routing failure whether it is observed from ChatGPT usage (401 token_invalidated) or OpenAI OAuth token refresh (400 invalid_refresh_token). Sidecar quota/runtime evidence must map terminal credential invalidation to account-scoped auth-error route guard so the OAuth account leaves runtime candidates, and the next fresh successful usage/quota observation or relogin must clear that auth-error. Account cards should show the visible 重新登录 action for active auth-file accounts when quota runtime degradedReason, blockReason, or sources[].reason proves token invalidation; 402 deactivated_workspace and usage_limit_reached remain error/quota displays, not automatic relogin CTAs.
  • Reset time is the recovery boundary for quota-empty: use the latest exhausted window reset as ExpiresAt, let active blocks expire naturally, and only successful fresh quota recovery should clear quota-empty before reset. Stale/cache writes must not clear an existing fresh block early.
  • Successful fresh quota recovery should clear quota-empty by sidecar guard identity lookup, not only by the original block key. This lets an accountKey quota refresh clear an earlier auth-scoped quota-empty for the same account while leaving manual-disabled and rate-limit sources intact.
  • For Codex WebSocket, candidate filtering alone is insufficient because downstream sessions may hold pinnedAuthID and an upstream connection. Add WebSocket-specific session control at request boundaries.
  • P0 behavior may close affected upstream sessions immediately when an auth is disabled. P2 behavior should preserve the downstream WebSocket and switch at the next downstream request boundary.
  • At the P2 boundary, check whether the current pinned auth is guarded before request normalization. If guarded, release the pin, close the old execution session upstream resource, force full transcript replay, and let AuthManager select again.
  • WebSocket request-boundary releases must stay explainable: return or log the active guard source and reason, and write the guard release into the websocket timeline/request trace so rate-limit and manual-disabled releases are distinguishable after the fact.
  • For pinned Codex WebSocket 401/402/403/429 errors before any downstream payload has been written, suppress the error event, release the pin, close the execution session, rebuild the request as full transcript replay, and retry the same downstream request so the user-visible turn can switch accounts. Once any payload was written, keep the no-mid-response-migration boundary.
  • The Codex WebSocket executor must not reuse a session connection across different authID or wsURL. When either changes, close the old upstream connection with an explicit reason such as auth_rotated and re-handshake.
  • Do not promise mid-response account migration. Switching during an actively streaming response is a cancel/replay feature and needs a separate safety design.
  • Rate-limit status DTOs should expose sidecar-owned explain fields through every bridge layer: active sources, rule id, strategy/window, current usage, limit, window start/end, next reset, last evaluated time, stale, and degraded reason. The frontend may render these fields but must not recompute blocked state locally.
  • Required tests for this class of change: route guard source independence, route guard active source detail lookup, rate-limit source refresh, management rollback on evaluation failure, evaluator serialization, manual disable service hook, rate-limit status explain DTO, pinned auth release after guard block, pinned auth release source/reason timeline, pre-payload pinned quota failover retries the same request, no stale previous_response_id after failover, and same-session upstream re-handshake when auth changes.

• Account Budget Guard / Route Engine Mock-First Testing:

  • When implementing or changing Route Engine, Account Budget Guard, route guard sources, quota-threshold rules, usage calibration, or related sidecar hot-path admission logic, start with mock upstream + mock downstream tests before real accounts, real quota refreshes, real Codex requests, or dev App hand testing.
  • Before each implementation slice, name the mock upstream facts and mock downstream/spy outputs in the test plan. If that pair is unclear, stop at research/planning and document the missing seam in the owning space instead of starting from live services.
  • Mock upstream facts should include fake quota windows, fake usage aggregators, injected clock, fake account inventory, fake live sessions, and fixture RouteRequestContext / request facts.
  • Mock downstream / spy outputs should include route decision sinks, fake executors, fake runtime source stores, calibration ledger writes, and Wails/frontend fixture DTOs.
  • Route guard simulators must not re-interpret rules separately from runtime. For quota-threshold, budget, daily / multi-day / bounded windows, or future rule families, extract a shared evaluator first, then require a same-facts gate proving simulator decision and runtime guard output agree on source, reason, action, and recovery/expiry boundary.
  • Sidecar service tests must isolate profile/HOME/config paths. Package-level TestMain, per-test temp profile config paths, or helper-level explicit path reset are preferred; tests must not read or write real ~/.config/gettokens* state, and persisted runtime state from one test must not leak into another test's mock evidence.
  • Time-bearing mock facts and ledgers must share the same injected clock. If a test posts calibration/rule/ledger entries through HTTP routes that default to server wall time, explicitly pass or derive created/revoked/effective timestamps so facts.now, runtime Upsert(now), expiry, and revoke checks are ordered deterministically; do not let real wall time decide whether a calibration is future-created, expired, or already revoked.
  • Cover the semantic edges before integration smoke: daily / multi-day / bounded windows, manual effective-usage calibration, calibration revoke, quota-threshold stale/degraded/unknown handling, drain not interrupting committed streams, block not calling executor, and provider quota-empty priority over local Budget.
  • Real sidecar/dev App/real-account checks are post-mock smoke only. If a behavior cannot be proven with mocks first, document the missing seam in the owning space before using live services as the primary verifier.
  • Detailed workflow lives in docs-linhay/dev/20260603-upstream-downstream-mock-testing.md; feature-specific evidence for the current evaluation lives in docs-linhay/spaces/20260618-route-guard-dsl-evaluation/.

• Browser Support: New Codex workspace tabs must be usable in a normal browser preview when the interaction is layout/config-flow checkable. Do not let missing window.go.main.App make the page blank; provide explicit preview data and visible preview-only save behavior.

• Frame URL Rule: Modal/detail layers opened from Codex workspaces should preserve the frame hash, for example #frame=codex&workspace=<key>&detail=<id>, when the surrounding feature already follows frame/detail routing. Closing a modal should remove only the detail marker.

• Wails Binding Boundary: Any Wails-facing Codex method added under internal/wailsapp must also be exposed through cmd/gettokens/app.go, mirrored in cmd/gettokens DTOs/mappers when needed, and regenerated into frontend/wailsjs. Frontend should import from generated bindings only after the main.App method exists.

• Raw + Structured Config Editors:

  • If a page provides both a structured editor and a raw config.toml editor, saving either path must reload or resync the other path before showing success.
  • Browser preview raw editors should edit in-memory preview text and label the result as preview-only; desktop editors should read/write the real file through Wails.
  • Raw saves must not bypass structured validation for later structured edits. After raw save, re-read the parsed snapshot and surface TOML errors instead of keeping stale rows.
  • For schema-backed config.toml pages, do not leave complex TOML tables permanently read-only just because they lack a fine-grained form. Use a raw TOML textarea for complex paths such as features.multi_agent_v2, notice.model_migrations, mcp_servers, skills, projects, profiles, and provider auth/http_headers/query_params.
  • Path-scoped raw TOML writes must validate every [section] / [[section]] header before saving. The header must match the target path or one of its child paths, for example skills may write [skills...] / [[skills...]], while model_providers.gettokens.auth may write only that provider auth subtree.