+
+Grok Register is a Python toolkit for automation workflow research, test-environment validation, and personal learning. It provides GUI / CLI / WebUI interfaces, four temporary-email services plus an Outlook mailbox pool, optional 1–8 worker concurrency, and an account-level proxy pool. It also integrates Chromium browser automation, safe account persistence, pending-result recovery, grok2api token-pool synchronization, and optional CPA xAI OIDC credential export.
+
+
Need stable residential IPs? Try IPWO residential proxies.
+
+
+Coverage across 195+ countries and regions
+Real residential IP resources
+Flexible IP rotation
+HTTP / HTTPS / SOCKS5 support
+
+
+
Suitable for automation registration, account management, data collection, and cross-border business scenarios, with flexible integration into browser automation tools and proxy pools. Free trial available. Discount code: 0205
+
+
For advertising partnerships, contact me at: 2309501984
+
+## Features
+
+Grok Register uses a real Chromium / Chrome browser to complete the registration flow, with GUI, CLI, and WebUI all connected to the same registration core.
+
+Key features:
+
+- Automatically opens the registration page, submits an email address, polls for the verification code, fills in profile information, and obtains the SSO cookie.
+- Supports five email sources: **DuckMail / YYDS / Cloudflare temporary email / Cloud Mail / Outlook mailbox pool**.
+- Supports three interfaces: **GUI / CLI / WebUI**.
+- Supports optional **1–8 worker concurrent registration**; disabled by default.
+- Supports `direct / single / pool` proxy modes, health checks, cooldowns, subscriptions, fixed/rotating nodes, and stable account-level Proxy Leases.
+- The proxy pool can parse mixed **HTTP / HTTPS / SOCKS / VLESS / VMess / Trojan / Hysteria2 / TUIC / Shadowsocks** nodes.
+- Can optionally attempt to enable NSFW after registration; failure does not discard an account that was already registered successfully.
+- Supports pre-storage SSO risk screening for `botFlagSource` / `policy=deny`; confirmed matches are quarantined and skipped for grok2api / CPA. Risk checks are fail-open: network failures, abnormal HTTP responses, or missing risk fields are logged for diagnostics and the account continues to storage.
+- Supports writing SSO tokens to either a local or remote grok2api pool.
+- Supports optional CPA xAI OIDC credential export and CLIProxyAPI hotload.
+- Successful accounts are persisted immediately. If writing the main account result fails, the result is placed in the corresponding `accounts_*.txt.pending.jsonl` file for later idempotent recovery. Failed risk-quarantine writes use a separate risk pending queue and are not mixed with normal account pending results.
+- Supports task stopping, browser restarts, email retries, runtime cleanup, and isolation of post-processing errors.
+
+The main flow for a single account is:
+
+```text
+Open registration page
+ → Create and submit email
+ → Retrieve and enter verification code
+ → Fill in profile
+ → Obtain SSO cookie
+ → Optionally enable NSFW
+ → SSO risk screening (botFlagSource / policy)
+ → Save account
+ → Optionally add to grok2api
+ → Optionally export CPA/OIDC
+```
+
+> grok2api pool insertion and CPA/OIDC are optional post-processing steps after registration. Post-processing failures are recorded as warnings and do not reclassify an already saved account as a registration failure. When SSO risk screening matches, the account is not written to the main account file and is not sent to grok2api / CPA.
+
+## Quick Start
+
+### 1. Requirements
+
+- Python **3.9+**
+- Google Chrome or Chromium
+- Network access to the registration page and the selected email API
+- Tkinter is required for the GUI; use the CLI or WebUI if Tkinter is unavailable
+- **sing-box is required only when using VLESS / VMess / Trojan / Hysteria2 / TUIC / Shadowsocks nodes**; HTTP/HTTPS/SOCKS continue to use the project's native proxy implementation
+
+### 2. Installation
+
+```bash
+git clone https://github.com/AaronL725/grok-register.git
+cd grok-register
+
+python -m venv .venv
+```
+
+Activate the virtual environment:
+
+```bash
+# Windows PowerShell
+.venv\Scripts\Activate.ps1
+
+# macOS / Linux
+source .venv/bin/activate
+```
+
+Install the core dependencies:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+```
+
+Copy the configuration file:
+
+```bash
+# macOS / Linux
+cp config.example.json config.json
+
+# Windows CMD
+copy config.example.json config.json
+```
+
+### 3. Start with the minimum configuration
+
+If you are starting with DuckMail, use the following minimal configuration:
+
+```json
+{
+ "email_provider": "duckmail",
+ "duckmail_api_key": "",
+ "register_count": 1,
+ "proxy_mode": "auto",
+ "proxy": "",
+ "multi_thread_enabled": false,
+ "cpa_export_enabled": false
+}
+```
+
+Then fill in the fields required by your selected `email_provider` and any post-processing features you enable. See [`config.example.json`](config.example.json) for the complete field list.
+
+> `config.example.json` is the complete configuration template. Values such as `example.com` and `temp-mail.example.com` are placeholders, not service addresses that can be used directly. If you use Cloudflare / Cloud Mail / YYDS, fill in the corresponding service parameters first.
+
+### 4. Launch
+
+GUI:
+
+```bash
+python grok_register_ttk.py
+```
+
+WebUI:
+
+```bash
+python -m pip install -r requirements-web.txt
+python -m web.server
+```
+
+Open:
+
+```text
+http://127.0.0.1:8092
+```
+
+> GUI, CLI, and WebUI share the same `config.json` and registration logic. It is recommended to run a task from only one interface at a time.
+
+## Usage
+
+### WebUI (optional)
+
+```bash
+python -m pip install -r requirements-web.txt
+python -m web.server
+```
+
+The WebUI listens on `127.0.0.1:8092` by default and provides bilingual Chinese/English configuration, start/stop controls, batch statistics, real-time logs, proxy-pool node status, subscription parsing statistics, reload, and manual testing.
+
+### GUI
+
+```bash
+python grok_register_ttk.py
+```
+
+The GUI lets you configure the main email, proxy, proxy-pool, multi-worker, and registration settings, then click "Start Registration".
+
+### CLI
+
+The following three commands are equivalent:
+
+```bash
+python grok_register_ttk.py cli
+python grok_register_ttk.py start
+python grok_register_ttk.py --cli
+```
+
+The CLI reads `config.json`. After validation, it prompts:
+
+```text
+> start
+```
+
+Enter `start` to begin. Press `Ctrl+C` to request a stop.
+
+> The CLI only omits the Tk GUI. The registration page still uses a real Chromium / Chrome browser.
+
+## Configuration
+
+The project performs structural validation at startup and checks fields required by currently enabled features only when a task actually starts. This allows you to open the GUI / WebUI first and configure the project incrementally.
+
+### Basic configuration
+
+| Setting | Description |
+| --- | --- |
+| `email_provider` | `duckmail` / `yyds` / `cloudflare` / `cloudmail` / `outlook` |
+| `register_count` | Number of registrations in the current batch |
+| `enable_nsfw` | Whether to attempt to enable NSFW after registration |
+| `sso_risk_gate_enabled` | Whether to check grok.com `botFlagSource` / `policy=deny` before storage; default `true` |
+| `sso_risk_rejected_file` | File for quarantined SSO records; default `./sso_risk_rejected.txt` |
+| `user_agent` | User-Agent used by Chromium and HTTP requests |
+| `proxy_mode` | `auto` / `direct` / `single` / `pool` |
+| `proxy` | Single proxy address; in `auto` mode, leave empty for a direct connection |
+| `multi_thread_enabled` | Whether concurrent registration is enabled; default `false` |
+| `multi_thread_workers` | Number of concurrent workers, range `1–8` |
+
+### Email services
+
+#### DuckMail
+
+```json
+{
+ "email_provider": "duckmail",
+ "duckmail_api_key": ""
+}
+```
+
+#### YYDS
+
+```json
+{
+ "email_provider": "yyds",
+ "yyds_api_key": "",
+ "yyds_jwt": ""
+}
+```
+
+At least one of `yyds_api_key` and `yyds_jwt` must be provided.
+
+#### Outlook mailbox pool
+
+Outlook mode uses existing Outlook / Microsoft mailboxes that can be read through OAuth2. It does not create Microsoft mailboxes. The configuration stores only the mailbox-pool file path:
+
+```json
+{
+ "email_provider": "outlook",
+ "outlook_accounts_file": "./output/mailboxes/outlook-accounts.txt"
+}
+```
+
+Each line in the mailbox pool uses the following format:
+
+```text
+email----password----clientId----refreshToken----auto
+```
+
+The final column is optional and supports `auto` / `imap` / `graph`; if omitted, it defaults to `auto`. The same fields separated by `|` are also supported. The `password` field is retained in the pool record, but verification-code retrieval uses `clientId + refreshToken` to obtain an OAuth2 access token.
+
+- `auto`: Before the email is submitted, independent pre-send cursors are established for IMAP and Microsoft Graph. Polling uses only the channels that actually passed preflight; if both are available, both are polled concurrently.
+- `imap`: Reads Inbox, Junk, Archive, and other common folders through `outlook.office365.com:993` + XOAUTH2. It uses `UIDVALIDITY + UID` as a stable incremental cursor instead of message counts or sequence numbers that can shift when messages are deleted or moved. Folder LIST results plus the IMAP connection/access token established during preflight are reused during the short verification-code window, and reconnected/refreshed only after disconnects or authentication expiry.
+- `graph`: Monitors both `Inbox` and `JunkEmail` through Microsoft Graph. It uses immutable message ID + `receivedDateTime` as the pre-send cursor, polls only lightweight message-frontier data during normal operation, and reads the message body only after a new message is confirmed.
+- Microsoft OAuth/Graph performs limited retries for timeouts, connection errors, `429`, and `5xx`. `429` responses honor `Retry-After` where possible; other retries use exponential backoff with jitter, and Microsoft HTTP concurrency is limited.
+- Verification codes are extracted only in explicit verification-code contexts, or when the sender is confirmed to belong to an official xAI/Grok domain, preventing ordinary ticket IDs such as `ABC-123` from being misidentified as OTPs.
+- Each mailbox can be allocated at most once per registration task. Multi-worker registration shares a task-level allocator. Mailbox sessions use one-time opaque handles that expire when verification-code retrieval begins; mailbox state/access tokens are released from memory immediately after retrieval ends.
+- A mailbox without a safe pre-send cursor is not submitted for registration. If the requested registration count exceeds the number of valid mailboxes in the pool, the task is automatically capped at the pool capacity.
+- Outlook refresh tokens / access tokens are not written to `mail_credentials.txt`, ordinary logs, or `config.json`. The mailbox-pool file is atomically written with `0600` permissions where possible and is included in `.gitignore`.
+
+The GUI's "Manage Outlook Mailbox Pool" and the WebUI mailbox-pool editor both provide health checks that can verify each mailbox's IMAP/Graph availability without triggering xAI registration. Results return only safe metadata such as email address, mode, channel status, and folders. The Web interface listens only on localhost and sets `no-store` on mailbox-pool-related responses.
+
+#### Cloudflare temporary email
+
+Common fields:
+
+| Setting | Description |
+| --- | --- |
+| `cloudflare_api_base` | Mail API base URL |
+| `cloudflare_api_key` | Authentication credential paired with `cloudflare_auth_mode`: may be empty for `none`; used as Bearer Token for `bearer`; as `X-API-Key` for `x-api-key`; as Admin Password for `x-admin-auth`; or as the URL `key` parameter for `query-key` |
+| `cloudflare_auth_mode` | `none` / `bearer` / `x-api-key` / `x-admin-auth` / `query-key` |
+| `cloudflare_path_accounts` | Mailbox-creation endpoint |
+| `cloudflare_path_messages` | Message-list endpoint |
+| `defaultDomains` | Default receiving domains; separate multiple domains with commas |
+
+Anonymous creation example:
+
+```json
+{
+ "email_provider": "cloudflare",
+ "cloudflare_api_base": "https://your-worker-api-domain",
+ "cloudflare_api_key": "",
+ "cloudflare_auth_mode": "none",
+ "cloudflare_path_accounts": "/api/new_address",
+ "cloudflare_path_messages": "/api/mails",
+ "defaultDomains": "example.com"
+}
+```
+
+Admin creation example:
+
+```json
+{
+ "email_provider": "cloudflare",
+ "cloudflare_api_base": "https://your-worker-api-domain",
+ "cloudflare_api_key": "your ADMIN_PASSWORD",
+ "cloudflare_auth_mode": "x-admin-auth",
+ "cloudflare_path_accounts": "/admin/new_address",
+ "cloudflare_path_messages": "/api/mails",
+ "defaultDomains": "example.com"
+}
+```
+
+#### Cloud Mail no-inbox mode
+
+```json
+{
+ "email_provider": "cloudmail",
+ "cloudmail_api_base": "https://your-Cloud-Mail-domain",
+ "cloudmail_public_token": "public API Token",
+ "cloudmail_domains": "example.com,example.net",
+ "cloudmail_path_messages": "/api/public/emailList"
+}
+```
+
+Cloud Mail's Public Token is placed directly in the `Authorization` header without a `Bearer` prefix. The upstream service currently stores only one global Public Token, so regenerating the token invalidates the old one.
+
+After the current registration slot / Proxy Lease is established and before the browser starts, the program checks Cloud Mail authentication through the same network exit. If it receives `401 token validation failed`, it waits about 70 seconds on the same exit for Workers KV convergence; it does not switch proxies, automatically generate a new token, or try alternate authentication formats.
+
+If 401 responses persist after the waiting window, check `cloudmail_api_base`, the Public Token, and whether the KV namespace actually bound to the Cloud Mail Worker belongs to the same deployment instance. Do not repeatedly regenerate tokens. Error logs record only the token length and a short SHA-256 fingerprint, never the full Public Token.
+
+## Proxy & Proxy Pool
+
+Default:
+
+```json
+{
+ "proxy_mode": "auto",
+ "proxy": ""
+}
+```
+
+`auto` preserves compatibility with the legacy single-proxy configuration: when `proxy` is empty, the connection is direct; when it is non-empty, that proxy is used.
+
+### Single proxy
+
+Native proxy:
+
+```json
+{
+ "proxy_mode": "single",
+ "proxy": "http://user:password@127.0.0.1:7890"
+}
+```
+
+`single` can also accept a supported advanced-protocol URI directly; advanced protocols require a local executable `sing-box`.
+
+### Proxy pool
+
+```json
+{
+ "proxy_mode": "pool",
+ "proxy_fallback": "none",
+ "proxy_pool_file": "./proxies.txt",
+ "proxy_pool_subscription_url": "",
+ "proxy_pool_endpoint_mode": "auto",
+ "proxy_pool_max_concurrent_per_node": 1,
+ "proxy_protocol_backend": "auto",
+ "proxy_singbox_path": "",
+ "proxy_protocol_start_timeout_sec": 10,
+ "proxy_runtime_idle_ttl_sec": 120,
+ "proxy_runtime_cache_max": 32
+}
+```
+
+Proxy sources can be plain text or an entire Base64-encoded document. After decoding, they may contain mixed protocols:
+
+```text
+http://...
+socks5://...
+vless://...
+vmess://...
+trojan://...
+hysteria2://...
+tuic://...
+ss://...
+```
+
+Currently supported:
+
+- HTTP / HTTPS / SOCKS / SOCKS4 / SOCKS4A / SOCKS5 / SOCKS5H
+- VLESS / VMess / Trojan / Hysteria2 (`hy2`) / TUIC / Shadowsocks (`ss`)
+- Local files and HTTP/HTTPS subscriptions
+- Standard Base64 and URL-safe Base64 subscriptions
+- Common VLESS/VMess/Trojan TCP/WS/gRPC/HTTP/HTTPUpgrade/QUIC transports
+- Common VLESS TLS / uTLS / Reality parameters
+- Node parsing statistics, health probes, failure cooldowns, and automatic recovery
+- Fixed/rotating endpoints, `{account}`, concurrency limits, and stable account-level Proxy Leases
+
+The proxy runtime uses a lazy + idle-cache design: a local runtime is created only when a node is actually selected, probed, or preflighted. Native proxies that need a unified HTTP exit use `LocalProxyBridge`; VLESS / VMess / Trojan / Hysteria2 / TUIC / Shadowsocks use sing-box. When the Lease reference count drops to 0, the runtime does not exit immediately by default; it moves into the idle cache. Defaults are `proxy_runtime_idle_ttl_sec=120` and `proxy_runtime_cache_max=32`. The runtime closes when TTL expires, the cache evicts it, or the Manager shuts down. Set `proxy_runtime_idle_ttl_sec=0` to restore immediate shutdown at zero references.
+
+Within a single account attempt, the browser, email, NSFW, and default CPA all stay on the same Lease. While waiting for a verification code, if no usable code has been obtained, the program may retry with a different email address while staying on the same Lease. Once verification-code entry/submission begins, later exceptions do not replay the registration by switching email or proxy; they are treated as an "outcome uncertain" state.
+
+For complete parameters, protocol mappings, runtime behavior, and health rules, see [`docs/proxy-pool.en.md`](docs/proxy-pool.en.md).
+
+## Optional Multi-Worker Registration
+
+Disabled by default:
+
+```json
+{
+ "multi_thread_enabled": false,
+ "multi_thread_workers": 4
+}
+```
+
+To enable concurrency:
+
+```json
+{
+ "multi_thread_enabled": true,
+ "multi_thread_workers": 4
+}
+```
+
+- Worker count ranges from `1–8` and never exceeds `register_count`.
+- Each worker uses its own email module and browser runtime state.
+- Shared outputs are protected by locks.
+- Proxy health state is shared across all workers, while each account has an independent Proxy Lease.
+
+## grok2api Token Pool
+
+All pool-insertion features are optional.
+
+### Local pool
+
+```json
+{
+ "grok2api_auto_add_local": true,
+ "grok2api_local_token_file": "",
+ "grok2api_pool_name": "ssoBasic"
+}
+```
+
+### Remote pool
+
+Remote mode supports two credential methods; choose one:
+
+1. `grok2api_remote_app_key`
+2. `grok2api_remote_admin_username` + `grok2api_remote_admin_password`
+
+```json
+{
+ "grok2api_auto_add_remote": true,
+ "grok2api_remote_base": "https://your-grok2api-domain",
+ "grok2api_remote_app_key": "",
+ "grok2api_remote_admin_username": "admin",
+ "grok2api_remote_admin_password": "your administrator password",
+ "grok2api_pool_name": "ssoBasic",
+ "grok2api_allow_legacy_full_save": false
+}
+```
+
+The two remote credential methods cannot be configured at the same time. The newer admin username/password mode requires HTTPS for non-local addresses; `localhost` / `127.0.0.1` / `::1` may use HTTP. The legacy `app_key` compatibility endpoint currently accepts HTTP/HTTPS, although HTTPS is still recommended for remote deployments.
+
+## CPA / xAI OIDC Export
+
+```json
+{
+ "cpa_export_enabled": true,
+ "cpa_auth_dir": "./cpa_auths",
+ "cpa_copy_to_hotload": false,
+ "cpa_hotload_dir": "",
+ "cpa_base_url": "https://cli-chat-proxy.grok.com/v1",
+ "cpa_proxy": "",
+ "cpa_headless": false,
+ "cpa_force_standalone": true,
+ "cpa_mint_timeout_sec": 300,
+ "cpa_mint_cookie_inject": true,
+ "cpa_oidc_request_timeout_sec": 15,
+ "cpa_oidc_poll_timeout_sec": 15,
+ "api_reverse_tools": ""
+}
+```
+
+- `cpa_copy_to_hotload=true` requires `cpa_hotload_dir`.
+- An explicit `cpa_proxy` always takes priority.
+- If `cpa_proxy` is not configured and the current account uses a Proxy Lease, CPA inherits the same exit, including localhost runtimes for advanced protocols.
+- CPA export failures are recorded only as post-processing warnings and do not delete saved accounts.
+
+## Outputs & Pending Recovery
+
+| File / Directory | Contents |
+| --- | --- |
+| `accounts_*.txt` | Successfully saved accounts, passwords, and SSO tokens |
+| `` | SSO records quarantined due to `botFlagSource=1/2` or `policy=deny`; default `./sso_risk_rejected.txt` |
+| `mail_credentials.txt` | Temporary email addresses and email credentials created during registration. Email credentials are persisted before registration submission immediately after mailbox creation, so this file may include attempts that later failed, were retried, or ended with an uncertain outcome |
+| `accounts_*.txt.pending.jsonl` | Normal account pending results for registrations that succeeded but could not be written to the main account result file; recover with `retry-pending` |
+| `.pending.jsonl` | Separate risk pending queue used when a quarantined account cannot be written to the main quarantine file; do not recover with the normal `retry-pending` command |
+| `` | Optional local grok2api token pool; defaults to `token.json` in the project directory when left empty |
+| `/xai-*.json` | Optional CPA xAI OIDC credentials; default directory `./cpa_auths` |
+| `/cpa_auth_failed.txt` | CPA export failure records |
+| `screenshots/` | CPA browser failure-debugging screenshots |
+
+### Recover pending results
+
+```bash
+python grok_register_ttk.py retry-pending [output-file]
+```
+
+Recovery uses file locks, deduplication, and atomic replacement. Repeating the operation does not write the same successfully recovered account more than once.
+
+> `retry-pending` is **only for normal account-result pending files** such as `accounts_*.txt.pending.jsonl`. It does not apply to `.pending.jsonl`. Risk pending is a separate quarantine queue; after successful recovery it should be written to the configured `sso_risk_rejected_file`. There is currently no corresponding CLI subcommand; the internal recovery entry point is `sso_risk.retry_sso_risk_pending_file()`.
+
+## Project Structure
+
+```text
+.
+├── grok_register_ttk.py # GUI / CLI entry point and main adapter layer
+├── registration_flow.py # Shared GUI / CLI / WebUI registration state machine, batch orchestration, and stage-aware retries
+├── registration_parallel.py # Optional multi-worker concurrency coordinator
+├── registration_browser.py # Chromium registration-page state and submission logic
+├── browser_runtime.py # Shared HTTP, Chromium Options, and proxy injection
+├── proxy_pool.py # Compatibility export layer for proxy_pool_v3
+├── proxy_pool_v3.py # Proxy-pool core: Source, Lease, health, cooldown, refresh, and Probe
+├── proxy_bridge.py # HTTP/HTTPS/SOCKS → localhost HTTP proxy bridge and Chromium compatibility
+├── proxy_protocols.py # HTTP/SOCKS/VLESS/VMess/Trojan/HY2/TUIC/SS subscription parsing
+├── proxy_protocol_runtime.py # Native bridge / sing-box lazy runtime and idle cache
+├── mail_service.py # Four email services
+├── app_config.py # Default configuration, validation, loading, and saving
+├── account_outputs.py # Account, pending, and token outputs
+├── sso_risk.py # SSO botFlag / policy early stop
+├── cpa_export.py # CPA/OIDC export entry point
+├── cpa_xai/ # CPA browser, OAuth, proxy helpers, and credential writing
+├── web/
+│ ├── server.py # FastAPI WebUI control layer
+│ ├── index.html # WebUI page
+│ ├── proxy-pool.js # Proxy-pool WebUI interactions
+│ └── proxy-pool.css # Proxy-pool WebUI styles
+├── docs/proxy-pool.en.md # Detailed proxy-pool documentation
+├── config.example.json # Complete configuration example
+├── requirements.txt # Core dependencies
+├── requirements-web.txt # Optional WebUI dependencies
+└── tests/ # Unit and compatibility regression tests
+```
+
+## FAQ
+
+### Why does the CLI still open a browser?
+
+The CLI only skips the Tk GUI. Registration-page interactions, verification-code submission, and SSO cookie retrieval still depend on a real Chromium / Chrome browser.
+
+### What should I do if the GUI does not start?
+
+Make sure your Python environment includes Tkinter. Linux distributions may require installing `python3-tk` separately. You can also use the CLI or WebUI instead.
+
+### Why are advanced-protocol nodes shown as unavailable?
+
+VLESS / VMess / Trojan / Hysteria2 / TUIC / Shadowsocks require a local sing-box installation. By default, the project searches the system `PATH`; you can also set `proxy_singbox_path` in the WebUI / `config.json`. HTTP/HTTPS/SOCKS are unaffected.
+
+### Why are some V2Ray subscription nodes skipped?
+
+The WebUI shows subscription protocol counts and parsing errors. Unmappable transports or invalid URIs cause only the affected node to be skipped; other valid nodes in the same subscription are unaffected. See [`docs/proxy-pool.en.md`](docs/proxy-pool.en.md) for the complete mapping scope.
+
+### Why can the GUI / WebUI open when the configuration file is incomplete?
+
+Configuration saving and runtime validation are separate. The interface can open and let you edit configuration first; the required fields for currently enabled services are checked only when registration starts.
+
+### What if grok2api or CPA fails after registration succeeds?
+
+The account itself still counts as successfully registered. These errors are counted only as post-processing warnings.
+
+### Will an NSFW enablement failure discard the account?
+
+No. NSFW is optional; the account is still saved if that step fails.
+
+### Why does the proxy pool display usernames and passwords?
+
+The current WebUI is designed for personal/local deployment and displays complete proxy nodes and authentication information. Do not expose the WebUI to untrusted networks.
+
+### Where can I find more detailed proxy-pool parameters?
+
+See [`docs/proxy-pool.en.md`](docs/proxy-pool.en.md).
+
+### Why does an account go into pending?
+
+A normal `accounts_*.txt.pending.jsonl` file means registration completed, but the main account-result file could not be written. Use `retry-pending` to recover it; there is no need to register the account again.
+
+If the file is `.pending.jsonl`, the account was explicitly identified by risk screening but could not be written to the main quarantine file. This is a separate risk pending queue and cannot be recovered with the normal `retry-pending`.
+
+## License
+
+[MIT](LICENSE).
+
+## Acknowledgments
+
+Thanks to [linux.do](https://linux.do) — a vibrant tech community where this project is shared and discussed.
+
+## Star History
+
+
+
+
+
+
+
+
diff --git a/README.md b/README.md
index 753f50d8..6e70f510 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@
[](https://github.com/AaronL725/grok-register)
+
+
+The proxy pool is an optional network layer for the main registration flow. By default, `proxy_mode=auto` preserves the legacy single-proxy/direct behavior from older configurations. Account-level `ProxyLease`, node scheduling, probing, and health feedback are enabled only when `single` or `pool` is explicitly selected.
+
+## Core Principles
+
+- **One stable lease per account attempt**: the browser, email requests, registration-stage HTTP traffic, NSFW, and CPA/OIDC unless explicitly overridden all share the same network exit.
+- **Safe retries take priority over blind replay**: a Lease may be released and the attempt restarted only before any stateful submission occurs. While waiting for a verification code, but before code submission starts, recovery may switch the email address while staying on the same Lease. Errors after stateful boundaries such as email submission, verification-code entry/submission, or profile submission are marked as outcome uncertain; the full registration flow is not automatically replayed through a different proxy.
+- **All managed network components consume a unified HTTP-compatible endpoint**: HTTP/SOCKS/advanced protocols are ultimately presented in a form consumable by Chromium, curl_cffi, urllib, CPA, and probes.
+- **Probe and Runtime Health are separate**: active probing answers "is it reachable right now?", while business health answers "how has it actually performed during real registrations?".
+- **Fixed and Rotating are handled separately**: fixed nodes use Health/Failure/Cooldown; rotating gateways track exit successes/failures and success rate without cooling the entire gateway because of one bad exit.
+- **Source-scoped Last-Known-Good**: file and subscription sources refresh independently; if one source temporarily fails to refresh, its most recent successful node set is retained.
+- **Backward compatibility by default**: `auto` / `direct` continue to use the legacy path and do not force managed-proxy behavior.
+
+## Unified Network Exit
+
+In `single` / `pool` mode:
+
+```text
+plain HTTP (no auth)
+ → original HTTP endpoint
+
+HTTP + auth / HTTPS proxy / SOCKS4 / SOCKS5
+ → LocalProxyBridge
+ → http://127.0.0.1:
+
+VLESS / VMess / Trojan / Hysteria2 / TUIC / Shadowsocks
+ → sing-box
+ → http://127.0.0.1:
+```
+
+All traffic then flows through:
+
+```text
+ProxyLease.proxy_url
+ ↓
+Chromium / curl_cffi / Mail / NSFW / CPA OAuth / CPA Browser / Probe / Preflight
+```
+
+`ProxyLease.source_uri` retains the original node URI for logs, WebUI display, and diagnostics.
+
+## Configuration
+
+```json
+{
+ "proxy_mode": "auto",
+ "proxy": "",
+ "proxy_fallback": "none",
+
+ "proxy_pool_file": "",
+ "proxy_pool_subscription_url": "",
+ "proxy_pool_subscription_proxy": "",
+ "proxy_pool_subscription_public_only": false,
+
+ "proxy_pool_endpoint_mode": "auto",
+ "proxy_pool_refresh_interval_sec": 900,
+ "proxy_pool_probe_interval_sec": 900,
+ "proxy_pool_probe_timeout_sec": 15,
+ "proxy_pool_probe_provider": "cloudflare",
+ "proxy_pool_probe_dual_stack": true,
+
+ "proxy_pool_max_concurrent_per_node": 1,
+ "proxy_pool_acquire_timeout_sec": 30,
+
+ "proxy_protocol_backend": "auto",
+ "proxy_singbox_path": "",
+ "proxy_protocol_start_timeout_sec": 10,
+ "proxy_runtime_idle_ttl_sec": 120,
+ "proxy_runtime_cache_max": 32,
+
+ "proxy_pool_persist_health": false,
+ "proxy_pool_state_file": "./proxy_pool_state.json",
+ "proxy_pool_preflight_enabled": true
+}
+```
+
+### `proxy_mode`
+
+| Value | Behavior |
+| --- | --- |
+| `auto` | Default compatibility mode; continues to use the legacy `proxy` behavior. |
+| `direct` | Forces the main registration flow to connect directly. |
+| `single` | Treats `proxy` as a single node managed by Lease and health logic. |
+| `pool` | Loads and schedules multiple nodes from a file and/or subscription. |
+
+### `proxy_fallback`
+
+| Value | Behavior |
+| --- | --- |
+| `none` | No fallback when no usable node is available. |
+| `direct` | A new attempt may fall back to a direct connection if Lease acquisition fails or times out. |
+| `single` | A new attempt may fall back to `proxy` if Lease acquisition fails or times out. |
+
+Fallback occurs only before a new account attempt begins. It never silently changes IP during an in-progress registration flow.
+
+## Registration Safe-Retry Boundary
+
+The managed registration flow tracks the current stage:
+
+```text
+lease_acquire
+browser_start
+page_open
+email_submit
+code_wait
+code_submit
+profile_submit
+sso_wait
+account_confirmed
+postprocess
+```
+
+Retry rules:
+
+```text
+lease_acquire / browser_start / page_open
+→ SAFE_NEW_LEASE
+→ release the old Lease and restart is allowed
+
+code_wait
+→ SAME_LEASE_RECOVERY
+→ keep the current Lease, switch email, restart the browser, and continue
+
+email_submit / code_submit / profile_submit / sso_wait
+→ OUTCOME_UNCERTAIN
+→ do not replay the full registration by switching email or proxy
+
+account_confirmed / postprocess
+→ NO_RETRY
+→ a confirmed account is not registered again
+```
+
+This avoids replaying a registration through a new IP after a submission may already have reached the server but the local client lost the response, reducing duplicate accounts and duplicate submissions. Only when the flow is still at `code_wait` and no usable verification code has been obtained may recovery switch the email address while keeping the same account Lease. Once `code_submit` begins, an unconfirmed submission result is counted as outcome uncertain and email retries no longer bypass the safe-retry boundary.
+
+The WebUI additionally tracks an `uncertain` count.
+
+## Supported Protocols
+
+Proxy sources may contain any mix of:
+
+```text
+HTTP / HTTPS
+SOCKS / SOCKS4 / SOCKS4A / SOCKS5 / SOCKS5H
+VLESS
+VMess
+Trojan
+Hysteria2 / hy2
+TUIC
+Shadowsocks / ss
+```
+
+Advanced protocols are converted on demand by sing-box into a local HTTP endpoint. If `proxy_singbox_path` is empty, the project looks for `sing-box` in the system `PATH`; it does not automatically download or update it.
+
+Shadowsocks supports common SIP002 / legacy Base64 URIs. The built-in implementation currently supports common AEAD / 2022 methods; unsupported plugins or methods produce explicit errors rather than silently degrading.
+
+## Native URI Normalization
+
+Native HTTP/HTTPS/SOCKS proxies must identify an explicit proxy endpoint:
+
+```text
+scheme://[user:password@]host:port
+```
+
+Rules:
+
+- A port is required.
+- Routing paths or query strings are not accepted.
+- `#fragment` is used only as the display name and is excluded from the canonical URI / node identity.
+- `{account}` may appear at most once and only in the proxy username.
+- `socks://` is normalized to `socks5://`.
+
+## SOCKS DNS Semantics
+
+The shared bridge explicitly distinguishes:
+
+```text
+socks5://
+→ resolve DNS locally
+→ send the IP address to the SOCKS server
+
+socks5h://
+→ do not resolve the hostname locally
+→ let the SOCKS server resolve the hostname
+```
+
+SOCKS4 / SOCKS4A likewise preserve local / remote DNS semantics respectively.
+
+## Runtime Idle Cache
+
+Runtimes are still created lazily; a large subscription does not cause a large number of bridge / sing-box runtimes to start all at once.
+
+After the reference count drops to 0, the runtime enters the idle cache by default:
+
+```text
+proxy_runtime_idle_ttl_sec = 120
+proxy_runtime_cache_max = 32
+```
+
+If the same node is acquired again within the TTL, the runtime can be reused directly. Once the TTL expires or the idle-cache limit is exceeded, the least recently used runtime is cleaned up. Set `proxy_runtime_idle_ttl_sec=0` to restore immediate shutdown at zero references. Manager shutdown closes all remaining runtimes.
+
+## Base64, Subscription Refresh, and Last-Known-Good
+
+`proxy_pool_file` and `proxy_pool_subscription_url` support:
+
+- Plain line-by-line URIs.
+- Entire documents encoded with standard Base64.
+- URL-safe Base64.
+- Mixed multi-protocol nodes.
+
+Each source is limited to 2 MiB and 10,000 nodes. Parsing results record total line count, Base64 status, successful node count, skipped count, protocol counts, and errors.
+
+File and subscription sources independently maintain:
+
+```text
+last_success_at
+last_error
+generation
+nodes
+diagnostics
+```
+
+For example, if the file refresh succeeds but the subscription temporarily times out:
+
+```text
+file → use the latest generation
+subscription → retain the last successful generation and mark it stale
+```
+
+A successful refresh from one source does not clear the most recent successful nodes from another source that temporarily failed.
+
+## Subscription Target Restrictions (Optional)
+
+When `proxy_pool_subscription_public_only=true`, the initial subscription URL and every HTTP redirect are revalidated:
+
+- Only `http` / `https` are allowed.
+- The hostname must resolve.
+- Private / loopback / link-local / multicast / reserved / unspecified addresses are rejected.
+- At most 3 redirects are allowed.
+- The response remains subject to the 2 MiB content limit.
+
+This option is disabled by default so local research environments can continue to use LAN or self-hosted subscription services.
+
+## Probe: IPv4 / IPv6 and False-Positive Protection
+
+Supported settings:
+
+```text
+proxy_pool_probe_provider = cloudflare | ipinfo
+proxy_pool_probe_dual_stack = true | false
+```
+
+With dual-stack enabled, IPv4 and IPv6 are probed independently and store:
+
+```text
+status
+tested_at
+latency_ms
+exit_ip
+error
+```
+
+If one family works and the other fails, the node may still be considered usable while retaining the independent results for both families.
+
+**HTTP 2xx no longer automatically means a healthy probe.** A probe must satisfy all of the following:
+
+```text
+HTTP 2xx
++ successfully parse a valid exit IP
++ IP family matches the current IPv4/IPv6 probe
+```
+
+Otherwise it is marked `unhealthy`, preventing false positives such as "HTTP 200 but malformed response / no IP".
+
+## Probe-Aware Soft Selection
+
+Node scheduling first requires:
+
+```text
+enabled
+not retired
+capacity available
+fixed node not cooling
+```
+
+It then groups nodes by recent probe status:
+
+```text
+Tier 0: recent healthy
+Tier 1: unknown / stale
+Tier 2: recent unhealthy
+```
+
+Affinity / health / inflight selection is performed from the best available tier first. Recent unhealthy status is a **soft deprioritization**, not a permanent hard ban; if it is the only available node, it may still be tried.
+
+## Fixed and Rotating Health Models
+
+### Fixed node
+
+Real registration success:
+
+```text
+registration_successes += 1
+business_samples += 1
+health = min(1.0, health + 0.1)
+failure_count = 0
+cooldown = none
+```
+
+Confirmed transport failure:
+
+```text
+transport_failures += 1
+business_samples += 1
+failure_count += 1
+health = max(0.05, health * 0.7)
+```
+
+Cooldown:
+
+```text
+30s → 60s → 120s → 240s → 480s → max 600s
+```
+
+### Rotating gateway
+
+A rotating gateway does not display fixed-node Health and does not apply a gateway-wide cooldown because of one bad exit. It records:
+
+```text
+exit_successes
+exit_failures
+gateway_success_rate
+```
+
+This prevents a gateway that frequently changes exits from appearing permanently as `Health=1.0` simply because it accumulated successful samples.
+
+### Business sample deduplication
+
+A single account attempt contributes at most one business-health sample. If a suspected failure probe occurs after a successful attempt, that attempt is not counted twice as two business samples.
+
+**Configuration/authentication errors are not business-health samples.** They increment `configuration_failures` and mark the node unavailable, but do not reduce Health, increment `business_samples`, or enter exponential transport cooldown.
+
+## Five Failure Categories
+
+Network feedback is divided into five categories:
+
+1. **compatibility**: an internal component/protocol contract is incompatible; node Health is not penalized.
+2. **configuration**: proxy authentication, credentials, or obvious configuration problems; the node is marked unavailable but the event is not counted as a transport Health sample.
+3. **hard_transport**: explicit exit-transport failures such as proxy connection failure, SOCKS CONNECT, HTTP CONNECT, or network unreachable; fixed-node Health is reduced and cooldown applies.
+4. **suspected_transport**: TLS, EOF, reset, timeout, and similar errors that may come from either the proxy or target path; the node is immediately reprobed and is penalized only if that reprobe also fails.
+5. **application**: application-layer conditions such as 401, 429, normal OAuth states, or business parameters; proxy-node Health is not penalized.
+
+## Structured Bridge Diagnostics
+
+LocalProxyBridge no longer swallows internal exceptions as generic EOFs. It records structured failure kinds such as:
+
+```text
+upstream_connect
+http_proxy_auth
+http_connect
+socks_auth
+socks_connect
+https_proxy_tls
+local_dns
+remote_dns
+remote_reset
+bridge
+```
+
+ProxyPool prioritizes these structured diagnostics for classification; string matching is only a fallback.
+
+## NSFW / CPA Post-Processing
+
+NSFW or CPA failures do not discard or re-register an account that was already registered successfully.
+
+- Explicit proxy transport error → feed back into the corresponding proxy category.
+- TLS/EOF/timeout → treat as suspected and reprobe immediately before deciding whether to penalize.
+- compatibility/config/application → handle according to the corresponding category.
+- Both an explicit CPA `cpa_proxy` and the Registration Lease are first converted to HTTP-compatible endpoints, preventing raw SOCKS URLs from being passed directly to network components that do not support that scheme.
+
+## Registration-Path Preflight (Optional)
+
+A non-destructive node-path preflight is provided for:
+
+```text
+accounts.x.ai
+grok.com
+```
+
+It checks only reachability, HTTP status, latency, and obvious Cloudflare block indications. It does not create mailboxes, create accounts, modify account settings, or count as a Runtime Health sample.
+
+Web API:
+
+```text
+POST /api/proxy-pool/preflight?node_id=
+```
+
+Manual preflight is disabled while a task is running. It can be turned off entirely with:
+
+```text
+proxy_pool_preflight_enabled = false
+```
+
+## Health-State Persistence (Optional)
+
+Default:
+
+```text
+proxy_pool_persist_health = false
+```
+
+When enabled, node business-health state is atomically written to:
+
+```text
+proxy_pool_state_file = ./proxy_pool_state.json
+```
+
+After the Manager is rebuilt, nodes with the same stable node ID restore Health, business counters, Failure/Cooldown state, and recent business errors. This file is included in `.gitignore` by default.
+
+## WebUI
+
+The proxy-pool page displays or stores:
+
+- Full node URI.
+- protocol / backend / fixed-or-rotating.
+- IPv4 / IPv6 probe results.
+- fixed Runtime Health or rotating gateway success rate.
+- business / transport / configuration counters.
+- inflight / cooldown / recent error.
+- subscription LKG / stale diagnostics.
+- dual-stack, runtime cache, health persistence, public-only subscription, preflight, and related settings.
+
+Web API:
+
+```text
+GET /api/proxy-pool/status
+POST /api/proxy-pool/reload
+POST /api/proxy-pool/test
+POST /api/proxy-pool/preflight?node_id=
+```
+
+Under the project's current local-use model, the WebUI, status API, and related logs continue to display full proxy addresses, including authentication information.
+
+## Compatibility Boundary
+
+The V3 behavior described here is concentrated in managed `single` / `pool` mode. The default `proxy_mode=auto` continues to preserve the legacy GUI/CLI/WebUI, email, result persistence, pending, token sync, and proxy behavior.
+
+Ordinary HTTP/SOCKS does not start sing-box merely because advanced-protocol support exists. VLESS/VMess/Trojan/Hysteria2/TUIC/Shadowsocks require sing-box only when actually acquired, probed, or preflighted.
diff --git a/docs/proxy-pool.md b/docs/proxy-pool.md
index f1e93beb..cd4ebfe7 100644
--- a/docs/proxy-pool.md
+++ b/docs/proxy-pool.md
@@ -1,5 +1,7 @@
# 注册代理池
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+