Merge pull request #460 from telemt/bump

Update Cargo.toml

.github/instructions/rust_rules.instructions.md

@@ -0,0 +1,135 @@
+---
+description: 'Rust programming language coding conventions and best practices'
+applyTo: '**/*.rs'
+---
+
+# Rust Coding Conventions and Best Practices
+
+Follow idiomatic Rust practices and community standards when writing Rust code. 
+
+These instructions are based on [The Rust Book](https://doc.rust-lang.org/book/), [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/), [RFC 430 naming conventions](https://github.com/rust-lang/rfcs/blob/master/text/0430-finalizing-naming-conventions.md), and the broader Rust community at [users.rust-lang.org](https://users.rust-lang.org).
+
+## General Instructions
+
+- Always prioritize readability, safety, and maintainability.
+- Use strong typing and leverage Rust's ownership system for memory safety.
+- Break down complex functions into smaller, more manageable functions.
+- For algorithm-related code, include explanations of the approach used.
+- Write code with good maintainability practices, including comments on why certain design decisions were made.
+- Handle errors gracefully using `Result<T, E>` and provide meaningful error messages.
+- For external dependencies, mention their usage and purpose in documentation.
+- Use consistent naming conventions following [RFC 430](https://github.com/rust-lang/rfcs/blob/master/text/0430-finalizing-naming-conventions.md).
+- Write idiomatic, safe, and efficient Rust code that follows the borrow checker's rules.
+- Ensure code compiles without warnings.
+
+## Patterns to Follow
+
+- Use modules (`mod`) and public interfaces (`pub`) to encapsulate logic.
+- Handle errors properly using `?`, `match`, or `if let`.
+- Use `serde` for serialization and `thiserror` or `anyhow` for custom errors.
+- Implement traits to abstract services or external dependencies.
+- Structure async code using `async/await` and `tokio` or `async-std`.
+- Prefer enums over flags and states for type safety.
+- Use builders for complex object creation.
+- Split binary and library code (`main.rs` vs `lib.rs`) for testability and reuse.
+- Use `rayon` for data parallelism and CPU-bound tasks.
+- Use iterators instead of index-based loops as they're often faster and safer.
+- Use `&str` instead of `String` for function parameters when you don't need ownership.
+- Prefer borrowing and zero-copy operations to avoid unnecessary allocations.
+
+### Ownership, Borrowing, and Lifetimes
+
+- Prefer borrowing (`&T`) over cloning unless ownership transfer is necessary.
+- Use `&mut T` when you need to modify borrowed data.
+- Explicitly annotate lifetimes when the compiler cannot infer them.
+- Use `Rc<T>` for single-threaded reference counting and `Arc<T>` for thread-safe reference counting.
+- Use `RefCell<T>` for interior mutability in single-threaded contexts and `Mutex<T>` or `RwLock<T>` for multi-threaded contexts.
+
+## Patterns to Avoid
+
+- Don't use `unwrap()` or `expect()` unless absolutely necessary—prefer proper error handling.
+- Avoid panics in library code—return `Result` instead.
+- Don't rely on global mutable state—use dependency injection or thread-safe containers.
+- Avoid deeply nested logic—refactor with functions or combinators.
+- Don't ignore warnings—treat them as errors during CI.
+- Avoid `unsafe` unless required and fully documented.
+- Don't overuse `clone()`, use borrowing instead of cloning unless ownership transfer is needed.
+- Avoid premature `collect()`, keep iterators lazy until you actually need the collection.
+- Avoid unnecessary allocations—prefer borrowing and zero-copy operations.
+
+## Code Style and Formatting
+
+- Follow the Rust Style Guide and use `rustfmt` for automatic formatting.
+- Keep lines under 100 characters when possible.
+- Place function and struct documentation immediately before the item using `///`.
+- Use `cargo clippy` to catch common mistakes and enforce best practices.
+
+## Error Handling
+
+- Use `Result<T, E>` for recoverable errors and `panic!` only for unrecoverable errors.
+- Prefer `?` operator over `unwrap()` or `expect()` for error propagation.
+- Create custom error types using `thiserror` or implement `std::error::Error`.
+- Use `Option<T>` for values that may or may not exist.
+- Provide meaningful error messages and context.
+- Error types should be meaningful and well-behaved (implement standard traits).
+- Validate function arguments and return appropriate errors for invalid input.
+
+## API Design Guidelines
+
+### Common Traits Implementation
+Eagerly implement common traits where appropriate:
+- `Copy`, `Clone`, `Eq`, `PartialEq`, `Ord`, `PartialOrd`, `Hash`, `Debug`, `Display`, `Default`
+- Use standard conversion traits: `From`, `AsRef`, `AsMut`
+- Collections should implement `FromIterator` and `Extend`
+- Note: `Send` and `Sync` are auto-implemented by the compiler when safe; avoid manual implementation unless using `unsafe` code
+
+### Type Safety and Predictability
+- Use newtypes to provide static distinctions
+- Arguments should convey meaning through types; prefer specific types over generic `bool` parameters
+- Use `Option<T>` appropriately for truly optional values
+- Functions with a clear receiver should be methods
+- Only smart pointers should implement `Deref` and `DerefMut`
+
+### Future Proofing
+- Use sealed traits to protect against downstream implementations
+- Structs should have private fields
+- Functions should validate their arguments
+- All public types must implement `Debug`
+
+## Testing and Documentation
+
+- Write comprehensive unit tests using `#[cfg(test)]` modules and `#[test]` annotations.
+- Use test modules alongside the code they test (`mod tests { ... }`).
+- Write integration tests in `tests/` directory with descriptive filenames.
+- Write clear and concise comments for each function, struct, enum, and complex logic.
+- Ensure functions have descriptive names and include comprehensive documentation.
+- Document all public APIs with rustdoc (`///` comments) following the [API Guidelines](https://rust-lang.github.io/api-guidelines/).
+- Use `#[doc(hidden)]` to hide implementation details from public documentation.
+- Document error conditions, panic scenarios, and safety considerations.
+- Examples should use `?` operator, not `unwrap()` or deprecated `try!` macro.
+
+## Project Organization
+
+- Use semantic versioning in `Cargo.toml`.
+- Include comprehensive metadata: `description`, `license`, `repository`, `keywords`, `categories`.
+- Use feature flags for optional functionality.
+- Organize code into modules using `mod.rs` or named files.
+- Keep `main.rs` or `lib.rs` minimal - move logic to modules.
+
+## Quality Checklist
+
+Before publishing or reviewing Rust code, ensure:
+
+### Core Requirements
+- [ ] **Naming**: Follows RFC 430 naming conventions
+- [ ] **Traits**: Implements `Debug`, `Clone`, `PartialEq` where appropriate
+- [ ] **Error Handling**: Uses `Result<T, E>` and provides meaningful error types
+- [ ] **Documentation**: All public items have rustdoc comments with examples
+- [ ] **Testing**: Comprehensive test coverage including edge cases
+
+### Safety and Quality
+- [ ] **Safety**: No unnecessary `unsafe` code, proper error handling
+- [ ] **Performance**: Efficient use of iterators, minimal allocations
+- [ ] **API Design**: Functions are predictable, flexible, and type-safe
+- [ ] **Future Proofing**: Private fields in structs, sealed traits where appropriate
+- [ ] **Tooling**: Code passes `cargo fmt`, `cargo clippy`, and `cargo test`

.github/instructions/self-explanatory-code-commenting.instructions.md

@@ -0,0 +1,162 @@
+---
+description: 'Guidelines for GitHub Copilot to write comments to achieve self-explanatory code with less comments. Examples are in JavaScript but it should work on any language that has comments.'
+applyTo: '**'
+---
+
+# Self-explanatory Code Commenting Instructions
+
+## Core Principle
+**Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT.**
+We do not need comments most of the time.
+
+## Commenting Guidelines
+
+### ❌ AVOID These Comment Types
+
+**Obvious Comments**
+```javascript
+// Bad: States the obvious
+let counter = 0;  // Initialize counter to zero
+counter++;  // Increment counter by one
+```
+
+**Redundant Comments**
+```javascript
+// Bad: Comment repeats the code
+function getUserName() {
+    return user.name;  // Return the user's name
+}
+```
+
+**Outdated Comments**
+```javascript
+// Bad: Comment doesn't match the code
+// Calculate tax at 5% rate
+const tax = price * 0.08;  // Actually 8%
+```
+
+### ✅ WRITE These Comment Types
+
+**Complex Business Logic**
+```javascript
+// Good: Explains WHY this specific calculation
+// Apply progressive tax brackets: 10% up to 10k, 20% above
+const tax = calculateProgressiveTax(income, [0.10, 0.20], [10000]);
+```
+
+**Non-obvious Algorithms**
+```javascript
+// Good: Explains the algorithm choice
+// Using Floyd-Warshall for all-pairs shortest paths
+// because we need distances between all nodes
+for (let k = 0; k < vertices; k++) {
+    for (let i = 0; i < vertices; i++) {
+        for (let j = 0; j < vertices; j++) {
+            // ... implementation
+        }
+    }
+}
+```
+
+**Regex Patterns**
+```javascript
+// Good: Explains what the regex matches
+// Match email format: username@domain.extension
+const emailPattern = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+```
+
+**API Constraints or Gotchas**
+```javascript
+// Good: Explains external constraint
+// GitHub API rate limit: 5000 requests/hour for authenticated users
+await rateLimiter.wait();
+const response = await fetch(githubApiUrl);
+```
+
+## Decision Framework
+
+Before writing a comment, ask:
+1. **Is the code self-explanatory?** → No comment needed
+2. **Would a better variable/function name eliminate the need?** → Refactor instead
+3. **Does this explain WHY, not WHAT?** → Good comment
+4. **Will this help future maintainers?** → Good comment
+
+## Special Cases for Comments
+
+### Public APIs
+```javascript
+/**
+ * Calculate compound interest using the standard formula.
+ * 
+ * @param {number} principal - Initial amount invested
+ * @param {number} rate - Annual interest rate (as decimal, e.g., 0.05 for 5%)
+ * @param {number} time - Time period in years
+ * @param {number} compoundFrequency - How many times per year interest compounds (default: 1)
+ * @returns {number} Final amount after compound interest
+ */
+function calculateCompoundInterest(principal, rate, time, compoundFrequency = 1) {
+    // ... implementation
+}
+```
+
+### Configuration and Constants
+```javascript
+// Good: Explains the source or reasoning
+const MAX_RETRIES = 3;  // Based on network reliability studies
+const API_TIMEOUT = 5000;  // AWS Lambda timeout is 15s, leaving buffer
+```
+
+### Annotations
+```javascript
+// TODO: Replace with proper user authentication after security review
+// FIXME: Memory leak in production - investigate connection pooling
+// HACK: Workaround for bug in library v2.1.0 - remove after upgrade
+// NOTE: This implementation assumes UTC timezone for all calculations
+// WARNING: This function modifies the original array instead of creating a copy
+// PERF: Consider caching this result if called frequently in hot path
+// SECURITY: Validate input to prevent SQL injection before using in query
+// BUG: Edge case failure when array is empty - needs investigation
+// REFACTOR: Extract this logic into separate utility function for reusability
+// DEPRECATED: Use newApiFunction() instead - this will be removed in v3.0
+```
+
+## Anti-Patterns to Avoid
+
+### Dead Code Comments
+```javascript
+// Bad: Don't comment out code
+// const oldFunction = () => { ... };
+const newFunction = () => { ... };
+```
+
+### Changelog Comments
+```javascript
+// Bad: Don't maintain history in comments
+// Modified by John on 2023-01-15
+// Fixed bug reported by Sarah on 2023-02-03
+function processData() {
+    // ... implementation
+}
+```
+
+### Divider Comments
+```javascript
+// Bad: Don't use decorative comments
+//=====================================
+// UTILITY FUNCTIONS
+//=====================================
+```
+
+## Quality Checklist
+
+Before committing, ensure your comments:
+- [ ] Explain WHY, not WHAT
+- [ ] Are grammatically correct and clear
+- [ ] Will remain accurate as code evolves
+- [ ] Add genuine value to code understanding
+- [ ] Are placed appropriately (above the code they describe)
+- [ ] Use proper spelling and professional language
+
+## Summary
+
+Remember: **The best comment is the one you don't need to write because the code is self-documenting.**

Cargo.lock

@@ -2087,7 +2087,7 @@ dependencies = [
 
 [[package]]
 name = "telemt"
-version = "3.1.3"
+version = "3.3.19"
 dependencies = [
  "aes",
  "anyhow",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "telemt"
-version = "3.3.9"
+version = "3.3.20"
 edition = "2024"
 
 [dependencies]
@@ -73,3 +73,6 @@ futures = "0.3"
 [[bench]]
 name = "crypto_bench"
 harness = false
+
+[profile.release]
+lto = "thin"

LICENSE

@@ -0,0 +1,165 @@
+###### TELEMT Public License 3 ######
+##### Copyright (c) 2026 Telemt #####
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this Software and associated documentation files (the "Software"),
+to use, reproduce, modify, prepare derivative works of, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, provided that all
+copyright notices, license terms, and conditions set forth in this License
+are preserved and complied with.
+
+### Official Translations
+
+The canonical version of this License is the English version.
+Official translations are provided for informational purposes only
+and for convenience, and do not have legal force. In case of any
+discrepancy, the English version of this License shall prevail.
+Available versions:
+- English in Markdown: docs/LICENSE/LICENSE.md
+- German: docs/LICENSE/LICENSE.de.md
+- Russian: docs/LICENSE/LICENSE.ru.md
+
+### License Versioning Policy
+
+This License is version 3 of the TELEMT Public License.
+Each version of the Software is licensed under the License that
+accompanies its corresponding source code distribution.
+
+Future versions of the Software may be distributed under a different
+version of the TELEMT Public License or under a different license,
+as determined by the Telemt maintainers.
+
+Any such change of license applies only to the versions of the
+Software distributed with the new license and SHALL NOT retroactively
+affect any previously released versions of the Software.
+
+Recipients of the Software are granted rights only under the License
+provided with the version of the Software they received.
+
+Redistributions of the Software, including Modified Versions, MUST
+preserve the copyright notices, license text, and conditions of this
+License for all portions of the Software derived from Telemt.
+
+Additional terms or licenses may be applied to modifications or
+additional code added by a redistributor, provided that such terms
+do not restrict or alter the rights granted under this License for
+the original Telemt Software.
+
+Nothing in this section limits the rights granted under this License
+for versions of the Software already released.
+
+### Definitions
+
+For the purposes of this License:
+- "Software" means the Telemt software, including source code, documentation,
+and any associated files distributed under this License.
+- "Contributor" means any person or entity that submits code, patches,
+documentation, or other contributions to the Software that are accepted
+into the Software by the maintainers.
+- "Contribution" means any work of authorship intentionally submitted
+to the Software for inclusion in the Software.
+- "Modified Version" means any version of the Software that has been
+changed, adapted, extended, or otherwise modified from the original
+Software.
+- "Maintainers" means the individuals or entities responsible for
+the official Telemt project and its releases.
+
+#### 1 Attribution
+
+Redistributions of the Software, in source or binary form, MUST RETAIN the
+above copyright notice, this license text, and any existing attribution
+notices.
+
+#### 2 Modification Notice
+
+If you modify the Software, you MUST clearly state that the Software has been
+modified and include a brief description of the changes made.
+
+Modified versions MUST NOT be presented as the original Telemt.
+
+#### 3 Trademark and Branding
+
+This license DOES NOT grant permission to use the name "Telemt", 
+the Telemt logo, or any Telemt trademarks or branding.
+
+Redistributed or modified versions of the Software MAY NOT use the Telemt
+name in a way that suggests endorsement or official origin without explicit
+permission from the Telemt maintainers.
+
+Use of the name "Telemt" to describe a modified version of the Software
+is permitted only if the modified version is clearly identified as a
+modified or unofficial version.
+
+Any distribution that could reasonably confuse users into believing that
+the software is an official Telemt release is prohibited.
+
+#### 4 Binary Distribution Transparency
+
+If you distribute compiled binaries of the Software,
+you are ENCOURAGED to provide access to the corresponding
+source code and build instructions where reasonably possible.
+
+This helps preserve transparency and allows recipients to verify the
+integrity and reproducibility of distributed builds.
+
+#### 5 Patent Grant and Defensive Termination Clause
+
+Each contributor grants you a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Software.
+
+This patent license applies only to those patent claims necessarily
+infringed by the contributor’s contribution alone or by combination of
+their contribution with the Software.
+
+If you initiate or participate in any patent litigation, including
+cross-claims or counterclaims, alleging that the Software or any
+contribution incorporated within the Software constitutes patent
+infringement, then **all rights granted to you under this license shall
+terminate immediately** as of the date such litigation is filed.
+
+Additionally, if you initiate legal action alleging that the
+Software itself infringes your patent or other intellectual
+property rights, then all rights granted to you under this
+license SHALL TERMINATE automatically.
+
+#### 6 Contributions
+
+Unless you explicitly state otherwise, any Contribution intentionally
+submitted for inclusion in the Software shall be licensed under the terms
+of this License.
+
+By submitting a Contribution, you grant the Telemt maintainers and all
+recipients of the Software the rights described in this License with
+respect to that Contribution.
+
+#### 7 Network Use Attribution
+
+If the Software is used to provide a publicly accessible network service,
+the operator of such service SHOULD provide attribution to Telemt in at least
+one of the following locations:
+
+- service documentation
+- service description
+- an "About" or similar informational page
+- other user-visible materials reasonably associated with the service
+
+Such attribution MUST NOT imply endorsement by the Telemt project or its
+maintainers.
+
+#### 8 Disclaimer of Warranty and Severability Clause
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE
+
+IF ANY PROVISION OF THIS LICENSE IS HELD TO BE INVALID OR UNENFORCEABLE,
+SUCH PROVISION SHALL BE INTERPRETED TO REFLECT THE ORIGINAL INTENT
+OF THE PARTIES AS CLOSELY AS POSSIBLE, AND THE REMAINING PROVISIONS
+SHALL REMAIN IN FULL FORCE AND EFFECT

LICENSING.md

@@ -1,17 +1,12 @@
 # LICENSING
 ## Licenses for Versions
-| Version | License       |
-|---------|---------------|
-| 1.0     | NO LICNESE    |
-| 1.1     | NO LICENSE    |
-| 1.2     | NO LICENSE    |
-| 2.0     | NO LICENSE    |
-| 3.0     | TELEMT UL 1   |
+| Version ≥ | Version ≤ | License       |
+|-----------|-----------|---------------|
+| 1.0       | 3.3.17    | NO LICNESE    |
+| 3.3.18    | 3.4.0     | TELEMT PL 3   |
 
 ### License Types
 - **NO LICENSE** = ***ALL RIGHT RESERVED***
-- **TELEMT UL1** - work in progress license for source code of `telemt`, which encourages:
-  - fair use, 
-  - contributions, 
-  - distribution, 
-  - but prohibits NOT mentioning the authors
+- **TELEMT PL** - special Telemt Public License based on Apache License 2 principles
+
+## [Telemt Public License 3](https://github.com/telemt/telemt/blob/main/LICENSE)

README.md

@@ -19,22 +19,9 @@
 
 ### 🇷🇺 RU
 
-#### Релиз 3.3.5 LTS - 6 марта
+#### Релиз 3.3.15 Semistable
 
-6 марта мы выпустили Telemt **3.3.5**
-
-Это [3.3.5 - первая LTS-версия telemt](https://github.com/telemt/telemt/releases/tag/3.3.5)!
-
-В ней используется:
-- новый алгоритм ME NoWait для непревзойдённо быстрого восстановления пула
-- Adaptive Floor, поддерживающий количество ME Writer на оптимальном уровне
-- модель усовершенствованного доступа к KDF Fingerprint на RwLock
-- строгая привязка Middle-End к DC-ID с предсказуемым алгоритмом деградации и самовосстановления
-
-Telemt Control API V1 в 3.3.5 включает:
-- несколько режимов работы в зависимости от доступных ресурсов
-- снапшот-модель для живых метрик без вмешательства в hot-path
-- минималистичный набор запросов для управления пользователями
+[3.3.15](https://github.com/telemt/telemt/releases/tag/3.3.15) по итогам работы в продакшн признан одним из самых стабильных и рекомендуется к использованию, когда cutting-edge фичи некритичны!
 
 Будем рады вашему фидбеку и предложениям по улучшению — особенно в части **API**, **статистики**, **UX**
 
@@ -53,22 +40,9 @@ Telemt Control API V1 в 3.3.5 включает:
 
 ### 🇬🇧 EN
 
-#### Release 3.3.5 LTS - March 6
+#### Release 3.3.15 Semistable
 
-On March 6, we released Telemt **3.3.3**
-
-This is [3.3.5 - the first LTS release of telemt](https://github.com/telemt/telemt/releases/tag/3.3.5)
-
-It introduces:
-- the new ME NoWait algorithm for exceptionally fast pool recovery
-- Adaptive Floor, which maintains the number of ME Writers at an optimal level
-- an improved KDF Fingerprint access model based on RwLock
-- strict binding of Middle-End instances to DC-ID with a predictable degradation and self-recovery algorithm
-
-Telemt Control API V1 in version 3.3.5 includes:
-- multiple operating modes depending on available resources
-- a snapshot-based model for live metrics without interfering with the hot path
-- a minimalistic request set for user management
+[3.3.15](https://github.com/telemt/telemt/releases/tag/3.3.15) is, based on the results of his work in production, recognized as one of the most stable and recommended for use when cutting-edge features are not so necessary!
 
 We are looking forward to your feedback and improvement proposals — especially regarding **API**, **statistics**, **UX**
 
@@ -104,28 +78,19 @@ We welcome ideas, architectural feedback, and pull requests.
 - Extensive logging via `trace` and `debug` with `RUST_LOG` method
 
 # GOTO
-- [Telemt - MTProxy on Rust + Tokio](#telemt---mtproxy-on-rust--tokio)
-  - [NEWS and EMERGENCY](#news-and-emergency)
-    - [✈️ Telemt 3 is released!](#️-telemt-3-is-released)
-    - [🇷🇺 RU](#-ru)
-      - [Релиз 3.3.5 LTS - 6 марта](#релиз-335-lts---6-марта)
-    - [🇬🇧 EN](#-en)
-      - [Release 3.3.5 LTS - March 6](#release-335-lts---march-6)
-- [Features](#features)
-- [GOTO](#goto)
-  - [Quick Start Guide](#quick-start-guide)
-  - [FAQ](#faq)
-    - [Recognizability for DPI and crawler](#recognizability-for-dpi-and-crawler)
-      - [Client WITH secret-key accesses the MTProxy resource:](#client-with-secret-key-accesses-the-mtproxy-resource)
-      - [Client WITHOUT secret-key gets transparent access to the specified resource:](#client-without-secret-key-gets-transparent-access-to-the-specified-resource)
-    - [Telegram Calls via MTProxy](#telegram-calls-via-mtproxy)
-    - [How does DPI see MTProxy TLS?](#how-does-dpi-see-mtproxy-tls)
-    - [Whitelist on IP](#whitelist-on-ip)
-    - [Too many open files](#too-many-open-files)
-  - [Build](#build)
-  - [Why Rust?](#why-rust)
-  - [Issues](#issues)
-  - [Roadmap](#roadmap)
+- [Quick Start Guide](#quick-start-guide)
+- [FAQ](#faq)
+  - [Recognizability for DPI and crawler](#recognizability-for-dpi-and-crawler)
+    - [Client WITH secret-key accesses the MTProxy resource:](#client-with-secret-key-accesses-the-mtproxy-resource)
+    - [Client WITHOUT secret-key gets transparent access to the specified resource:](#client-without-secret-key-gets-transparent-access-to-the-specified-resource)
+  - [Telegram Calls via MTProxy](#telegram-calls-via-mtproxy)
+  - [How does DPI see MTProxy TLS?](#how-does-dpi-see-mtproxy-tls)
+  - [Whitelist on IP](#whitelist-on-ip)
+  - [Too many open files](#too-many-open-files)
+- [Build](#build)
+- [Why Rust?](#why-rust)
+- [Issues](#issues)
+- [Roadmap](#roadmap)
 
 
 ## Quick Start Guide
@@ -273,6 +238,11 @@ git clone https://github.com/telemt/telemt
 cd telemt
 # Starting Release Build
 cargo build --release
+
+# Low-RAM devices (1 GB, e.g. NanoPi Neo3 / Raspberry Pi Zero 2):
+# release profile uses lto = "thin" to reduce peak linker memory.
+# If your custom toolchain overrides profiles, avoid enabling fat LTO.
+
 # Move to /bin
 mv ./target/release/telemt /bin
 # Make executable
@@ -281,6 +251,12 @@ chmod +x /bin/telemt
 telemt config.toml
 ```
 
+### OpenBSD
+- Build and service setup guide: [OpenBSD Guide (EN)](docs/OPENBSD.en.md)
+- Example rc.d script: [contrib/openbsd/telemt.rcd](contrib/openbsd/telemt.rcd)
+- Status: OpenBSD sandbox hardening with `pledge(2)` and `unveil(2)` is not implemented yet.
+
+
 ## Why Rust?
 - Long-running reliability and idempotent behavior
 - Rust's deterministic resource management - RAII 

config.full.toml

@@ -1,697 +0,0 @@
-# ==============================================================================
-#
-#   TELEMT — Advanced Rust-based Telegram MTProto Proxy
-#   Full Configuration Reference
-#
-#   This file is both a working config and a complete documentation.
-#   Every parameter is explained. Read it top to bottom before deploying.
-#
-#   Quick Start:
-#     1. Set [server].port to your desired port (443 recommended)
-#     2. Generate a secret: openssl rand -hex 16
-#     3. Put it in [access.users] under a name you choose
-#     4. Set [censorship].tls_domain to a popular unblocked HTTPS site
-#     5. Set your public IP in [general].middle_proxy_nat_ip
-#        and [general.links].public_host
-#     6. Set announce IP in [[server.listeners]]
-#     7. Run Telemt. It prints a tg:// link. Send it to your users.
-#
-#   Modes of Operation:
-#     Direct Mode  (use_middle_proxy = false)
-#       Connects straight to Telegram DCs via TCP. Simple, fast, low overhead.
-#       No ad_tag support. No CDN DC support (203, etc).
-#
-#     Middle-Proxy Mode  (use_middle_proxy = true)
-#       Connects to Telegram Middle-End servers via RPC protocol.
-#       Required for ad_tag monetization and CDN support.
-#       Requires proxy_secret_path and a valid public IP.
-#
-# ==============================================================================
-
-
-# ==============================================================================
-# LEGACY TOP-LEVEL FIELDS
-# ==============================================================================
-
-# Deprecated. Use [general.links].show instead.
-# Accepts "*" for all users, or an array like ["alice", "bob"].
-show_link = ["0"]
-
-# Fallback Datacenter index (1-5) when a client requests an unknown DC ID.
-# DC 2 is Amsterdam (Europe), closest for most CIS users.
-# default_dc = 2
-
-
-# ==============================================================================
-# GENERAL SETTINGS
-# ==============================================================================
-
-[general]
-
-# ------------------------------------------------------------------------------
-# Core Protocol
-# ------------------------------------------------------------------------------
-
-# Coalesce the MTProto handshake and first data payload into a single TCP packet.
-# Significantly reduces connection latency. No reason to disable.
-fast_mode = true
-
-# How the proxy connects to Telegram servers.
-# false = Direct TCP to Telegram DCs (simple, low overhead)
-# true  = Middle-End RPC protocol (required for ad_tag and CDN DCs)
-use_middle_proxy = true
-
-# 32-char hex Ad-Tag from @MTProxybot for sponsored channel injection.
-# Only works when use_middle_proxy = true.
-# Obtain yours: message @MTProxybot on Telegram, register your proxy.
-# ad_tag = "00000000000000000000000000000000"
-
-# ------------------------------------------------------------------------------
-# Middle-End Authentication
-# ------------------------------------------------------------------------------
-
-# Path to the Telegram infrastructure AES key file.
-# Auto-downloaded from https://core.telegram.org/getProxySecret on first run.
-# This key authenticates your proxy with Middle-End servers.
-proxy_secret_path = "proxy-secret"
-
-# ------------------------------------------------------------------------------
-# Public IP Configuration (Critical for Middle-Proxy Mode)
-# ------------------------------------------------------------------------------
-
-# Your server's PUBLIC IPv4 address.
-# Middle-End servers need this for the cryptographic Key Derivation Function.
-# If your server has a direct public IP, set it here.
-# If behind NAT (AWS, Docker, etc.), this MUST be your external IP.
-# If omitted, Telemt uses STUN to auto-detect (see middle_proxy_nat_probe).
-# middle_proxy_nat_ip = "203.0.113.10"
-
-# Auto-detect public IP via STUN servers defined in [network].
-# Set to false if you hardcoded middle_proxy_nat_ip above.
-# Set to true if you want automatic detection.
-middle_proxy_nat_probe = true
-
-# ------------------------------------------------------------------------------
-# Middle-End Connection Pool
-# ------------------------------------------------------------------------------
-
-# Number of persistent multiplexed RPC connections to ME servers.
-# All client traffic is routed through these "fat pipes".
-# 8 handles thousands of concurrent users comfortably.
-middle_proxy_pool_size = 8
-
-# Legacy field. Connections kept initialized but idle as warm standby.
-middle_proxy_warm_standby = 16
-
-# ------------------------------------------------------------------------------
-# Middle-End Keepalive
-# Telegram ME servers aggressively kill idle TCP connections.
-# These settings send periodic RPC_PING frames to keep pipes alive.
-# ------------------------------------------------------------------------------
-
-me_keepalive_enabled = true
-
-# Base interval between pings in seconds.
-me_keepalive_interval_secs = 25
-
-# Random jitter added to interval to prevent all connections pinging simultaneously.
-me_keepalive_jitter_secs = 5
-
-# Randomize ping payload bytes to prevent DPI from fingerprinting ping patterns.
-me_keepalive_payload_random = true
-
-# ------------------------------------------------------------------------------
-# Client-Side Limits
-# ------------------------------------------------------------------------------
-
-# Max buffered ciphertext per client (bytes) when upstream is slow.
-# Acts as backpressure to prevent memory exhaustion. 256KB is safe.
-crypto_pending_buffer = 262144
-
-# Maximum single MTProto frame size from client. 16MB is protocol standard.
-max_client_frame = 16777216
-
-# ------------------------------------------------------------------------------
-# Crypto Desynchronization Logging
-# Desync errors usually mean DPI/GFW is tampering with connections.
-# ------------------------------------------------------------------------------
-
-# true  = full forensics (trace ID, IP hash, hex dumps) for EVERY desync event
-# false = deduplicated logging, one entry per time window (prevents log spam)
-# Set true if you are actively debugging DPI interference.
-desync_all_full = true
-
-# ------------------------------------------------------------------------------
-# Beobachten — Built-in Honeypot / Active Probe Tracker
-# Tracks IPs that fail handshakes or behave like TLS scanners.
-# Output file can be fed into fail2ban or iptables for auto-blocking.
-# ------------------------------------------------------------------------------
-
-beobachten = true
-
-# How long (minutes) to remember a suspicious IP before expiring it.
-beobachten_minutes = 30
-
-# How often (seconds) to flush tracker state to disk.
-beobachten_flush_secs = 15
-
-# File path for the tracker output.
-beobachten_file = "cache/beobachten.txt"
-
-# ------------------------------------------------------------------------------
-# Hardswap — Zero-Downtime ME Pool Rotation
-# When Telegram updates ME server IPs, Hardswap creates a completely new pool,
-# waits until it is fully ready, migrates traffic, then kills the old pool.
-# Users experience zero interruption.
-# ------------------------------------------------------------------------------
-
-hardswap = true
-
-# ------------------------------------------------------------------------------
-# ME Pool Warmup Staggering
-# When creating a new pool, connections are opened one by one with delays
-# to avoid a burst of SYN packets that could trigger ISP flood protection.
-# ------------------------------------------------------------------------------
-
-me_warmup_stagger_enabled = true
-
-# Delay between each connection creation (milliseconds).
-me_warmup_step_delay_ms = 500
-
-# Random jitter added to the delay (milliseconds).
-me_warmup_step_jitter_ms = 300
-
-# ------------------------------------------------------------------------------
-# ME Reconnect Backoff
-# If an ME server drops the connection, Telemt retries with this strategy.
-# ------------------------------------------------------------------------------
-
-# Max simultaneous reconnect attempts per DC.
-me_reconnect_max_concurrent_per_dc = 8
-
-# Exponential backoff base (milliseconds).
-me_reconnect_backoff_base_ms = 500
-
-# Backoff ceiling (milliseconds). Will never wait longer than this.
-me_reconnect_backoff_cap_ms = 30000
-
-# Number of instant retries before switching to exponential backoff.
-me_reconnect_fast_retry_count = 12
-
-# ------------------------------------------------------------------------------
-# NAT Mismatch Behavior
-# If STUN-detected IP differs from local interface IP (you are behind NAT).
-# false = abort ME mode (safe default)
-# true  = force ME mode anyway (use if you know your NAT setup is correct)
-# ------------------------------------------------------------------------------
-
-stun_iface_mismatch_ignore = false
-
-# ------------------------------------------------------------------------------
-# Logging
-# ------------------------------------------------------------------------------
-
-# File to log unknown DC requests (DC IDs outside standard 1-5).
-unknown_dc_log_path = "unknown-dc.txt"
-
-# Verbosity: "debug" | "verbose" | "normal" | "silent"
-log_level = "normal"
-
-# Disable ANSI color codes in log output (useful for file logging).
-disable_colors = false
-
-# ------------------------------------------------------------------------------
-# FakeTLS Record Sizing
-# Buffer small MTProto packets into larger TLS records to mimic real HTTPS.
-# Real HTTPS servers send records close to MTU size (~1400 bytes).
-# A stream of tiny TLS records is a strong DPI signal.
-# Set to 0 to disable. Set to 1400 for realistic HTTPS emulation.
-# ------------------------------------------------------------------------------
-
-fast_mode_min_tls_record = 1400
-
-# ------------------------------------------------------------------------------
-# Periodic Updates
-# ------------------------------------------------------------------------------
-
-# How often (seconds) to re-fetch ME server lists and proxy secrets
-# from core.telegram.org. Keeps your proxy in sync with Telegram infrastructure.
-update_every = 300
-
-# How often (seconds) to force a Hardswap even if the ME map is unchanged.
-# Shorter intervals mean shorter-lived TCP flows, harder for DPI to profile.
-me_reinit_every_secs = 600
-
-# ------------------------------------------------------------------------------
-# Hardswap Warmup Tuning
-# Fine-grained control over how the new pool is warmed up before traffic switch.
-# ------------------------------------------------------------------------------
-
-me_hardswap_warmup_delay_min_ms = 1000
-me_hardswap_warmup_delay_max_ms = 2000
-me_hardswap_warmup_extra_passes = 3
-me_hardswap_warmup_pass_backoff_base_ms = 500
-
-# ------------------------------------------------------------------------------
-# Config Update Debouncing
-# Telegram sometimes pushes transient/broken configs. Debouncing requires
-# N consecutive identical fetches before applying a change.
-# ------------------------------------------------------------------------------
-
-# ME server list must be identical for this many fetches before applying.
-me_config_stable_snapshots = 2
-
-# Minimum seconds between config applications.
-me_config_apply_cooldown_secs = 300
-
-# Proxy secret must be identical for this many fetches before applying.
-proxy_secret_stable_snapshots = 2
-
-# ------------------------------------------------------------------------------
-# Proxy Secret Rotation
-# ------------------------------------------------------------------------------
-
-# Apply newly downloaded secrets at runtime without restart.
-proxy_secret_rotate_runtime = true
-
-# Maximum acceptable secret length (bytes). Rejects abnormally large secrets.
-proxy_secret_len_max = 256
-
-# ------------------------------------------------------------------------------
-# Hardswap Drain Settings
-# Controls graceful shutdown of old ME connections during pool rotation.
-# ------------------------------------------------------------------------------
-
-# Seconds to keep old connections alive for in-flight data before force-closing.
-me_pool_drain_ttl_secs = 90
-
-# Minimum ratio of healthy connections in new pool before draining old pool.
-# 0.8 = at least 80% of new pool must be ready.
-me_pool_min_fresh_ratio = 0.8
-
-# Maximum seconds to wait for drain to complete before force-killing.
-me_reinit_drain_timeout_secs = 120
-
-# ------------------------------------------------------------------------------
-# NTP Clock Check
-# MTProto uses timestamps. Clock drift > 30 seconds breaks handshakes.
-# Telemt checks on startup and warns if out of sync.
-# ------------------------------------------------------------------------------
-
-ntp_check = true
-ntp_servers = ["pool.ntp.org"]
-
-# ------------------------------------------------------------------------------
-# Auto-Degradation
-# If ME servers become completely unreachable (ISP blocking),
-# automatically fall back to Direct Mode so users stay connected.
-# ------------------------------------------------------------------------------
-
-auto_degradation_enabled = true
-
-# Number of DC groups that must be unreachable before triggering fallback.
-degradation_min_unavailable_dc_groups = 2
-
-
-# ==============================================================================
-# ALLOWED CLIENT PROTOCOLS
-# Only enable what you need. In censored regions, TLS-only is safest.
-# ==============================================================================
-
-[general.modes]
-
-# Classic MTProto. Unobfuscated length prefixes. Trivially detected by DPI.
-# No reason to enable unless you have ancient clients.
-classic = false
-
-# Obfuscated MTProto with randomized padding. Better than classic, but
-# still detectable by statistical analysis of packet sizes.
-secure = false
-
-# FakeTLS (ee-secrets). Wraps MTProto in TLS 1.3 framing.
-# To DPI, it looks like a normal HTTPS connection.
-# This should be the ONLY enabled mode in censored environments.
-tls = true
-
-
-# ==============================================================================
-# STARTUP LINK GENERATION
-# Controls what tg:// invite links are printed to console on startup.
-# ==============================================================================
-
-[general.links]
-
-# Which users to generate links for.
-# "*" = all users, or an array like ["alice", "bob"].
-show = "*"
-
-# IP or domain to embed in the tg:// link.
-# If omitted, Telemt uses STUN to auto-detect.
-# Set this to your server's public IP or domain for reliable links.
-# public_host = "proxy.example.com"
-
-# Port to embed in the tg:// link.
-# If omitted, uses [server].port.
-# public_port = 443
-
-
-# ==============================================================================
-# NETWORK & IP RESOLUTION
-# ==============================================================================
-
-[network]
-
-# Enable IPv4 for outbound connections to Telegram.
-ipv4 = true
-
-# Enable IPv6 for outbound connections to Telegram.
-ipv6 = false
-
-# Prefer IPv4 (4) or IPv6 (6) when both are available.
-prefer = 4
-
-# Experimental: use both IPv4 and IPv6 ME servers simultaneously.
-# May improve reliability but doubles connection count.
-multipath = false
-
-# STUN servers for external IP discovery.
-# Used for Middle-Proxy KDF (if nat_probe=true) and link generation.
-stun_servers = [
-    "stun.l.google.com:5349",
-    "stun1.l.google.com:3478",
-    "stun.gmx.net:3478",
-    "stun.l.google.com:19302"
-]
-
-# If UDP STUN is blocked, attempt TCP-based STUN as fallback.
-stun_tcp_fallback = true
-
-# If all STUN fails, use HTTP APIs to discover public IP.
-http_ip_detect_urls = [
-    "https://ifconfig.me/ip",
-    "https://api.ipify.org"
-]
-
-# Cache discovered public IP to this file to survive restarts.
-cache_public_ip_path = "cache/public_ip.txt"
-
-
-# ==============================================================================
-# SERVER BINDING & METRICS
-# ==============================================================================
-
-[server]
-
-# TCP port to listen on.
-# 443 is recommended (looks like normal HTTPS traffic).
-port = 443
-
-# IPv4 bind address. "0.0.0.0" = all interfaces.
-listen_addr_ipv4 = "0.0.0.0"
-
-# IPv6 bind address. "::" = all interfaces.
-listen_addr_ipv6 = "::"
-
-# Unix socket listener (for reverse proxy setups with Nginx/HAProxy).
-# listen_unix_sock = "/var/run/telemt.sock"
-# listen_unix_sock_perm = "0660"
-
-# Enable PROXY protocol header parsing.
-# Set true ONLY if Telemt is behind HAProxy/Nginx that injects PROXY headers.
-# If enabled without a proxy in front, clients will fail to connect.
-proxy_protocol = false
-
-# Prometheus metrics HTTP endpoint port.
-# Uncomment to enable. Access at http://your-server:9090/metrics
-# metrics_port = 9090
-
-# IP ranges allowed to access the metrics endpoint.
-metrics_whitelist = [
-    "127.0.0.1/32",
-    "::1/128"
-]
-
-# ------------------------------------------------------------------------------
-# Listener Overrides
-# Define explicit listeners with specific bind IPs and announce IPs.
-# The announce IP is what gets embedded in tg:// links and sent to ME servers.
-# You MUST set announce to your server's public IP for ME mode to work.
-# ------------------------------------------------------------------------------
-
-# [[server.listeners]]
-# ip = "0.0.0.0"
-# announce = "203.0.113.10"
-# reuse_allow = false
-
-
-# ==============================================================================
-# TIMEOUTS (seconds unless noted)
-# ==============================================================================
-
-[timeouts]
-
-# Maximum time for client to complete FakeTLS + MTProto handshake.
-client_handshake = 15
-
-# Maximum time to establish TCP connection to upstream Telegram DC.
-tg_connect = 10
-
-# TCP keepalive interval for client connections.
-client_keepalive = 60
-
-# Maximum client inactivity before dropping the connection.
-client_ack = 300
-
-# Instant retry count for a single ME endpoint before giving up on it.
-me_one_retry = 3
-
-# Timeout (milliseconds) for a single ME endpoint connection attempt.
-me_one_timeout_ms = 1500
-
-
-# ==============================================================================
-# ANTI-CENSORSHIP / FAKETLS / MASKING
-# This is where Telemt becomes invisible to Deep Packet Inspection.
-# ==============================================================================
-
-[censorship]
-
-# ------------------------------------------------------------------------------
-# TLS Domain Fronting
-# The SNI (Server Name Indication) your proxy presents to connecting clients.
-# Must be a popular, unblocked HTTPS website in your target country.
-# DPI sees traffic to this domain. Choose carefully.
-# Good choices: major CDNs, banks, government sites, search engines.
-# Bad choices: obscure sites, already-blocked domains.
-# ------------------------------------------------------------------------------
-
-tls_domain = "www.google.com"
-
-# ------------------------------------------------------------------------------
-# Active Probe Masking
-# When someone connects but fails the MTProto handshake (wrong secret),
-# they might be an ISP active prober testing if this is a proxy.
-#
-# mask = false: drop the connection (prober knows something is here)
-# mask = true:  transparently proxy them to mask_host (prober sees a real website)
-#
-# With mask enabled, your server is indistinguishable from a real web server
-# to anyone who doesn't have the correct secret.
-# ------------------------------------------------------------------------------
-
-mask = true
-
-# The real web server to forward failed handshakes to.
-# If omitted, defaults to tls_domain.
-# mask_host = "www.google.com"
-
-# Port on the mask host to connect to.
-mask_port = 443
-
-# Inject PROXY protocol header when forwarding to mask host.
-# 0 = disabled, 1 = v1, 2 = v2. Leave disabled unless mask_host expects it.
-# mask_proxy_protocol = 0
-
-# ------------------------------------------------------------------------------
-# TLS Certificate Emulation
-# ------------------------------------------------------------------------------
-
-# Size (bytes) of the locally generated fake TLS certificate.
-# Only used when tls_emulation is disabled.
-fake_cert_len = 2048
-
-# KILLER FEATURE: Real-Time TLS Emulation.
-# Telemt connects to tls_domain, fetches its actual TLS 1.3 certificate chain,
-# and exactly replicates the byte sizes of ServerHello and Certificate records.
-# Defeats DPI that uses TLS record length heuristics to detect proxies.
-# Strongly recommended in censored environments.
-tls_emulation = true
-
-# Directory to cache fetched TLS certificates.
-tls_front_dir = "tlsfront"
-
-# ------------------------------------------------------------------------------
-# ServerHello Timing
-# Real web servers take 30-150ms to respond to ClientHello due to network
-# latency and crypto processing. A proxy responding in <1ms is suspicious.
-# These settings add realistic delay to mimic genuine server behavior.
-# ------------------------------------------------------------------------------
-
-# Minimum delay before sending ServerHello (milliseconds).
-server_hello_delay_min_ms = 50
-
-# Maximum delay before sending ServerHello (milliseconds).
-server_hello_delay_max_ms = 150
-
-# ------------------------------------------------------------------------------
-# TLS Session Tickets
-# Real TLS 1.3 servers send 1-2 NewSessionTicket messages after handshake.
-# A server that sends zero tickets is anomalous and may trigger DPI flags.
-# Set this to match your tls_domain's behavior (usually 2).
-# ------------------------------------------------------------------------------
-
-# tls_new_session_tickets = 0
-
-# ------------------------------------------------------------------------------
-# Full Certificate Frequency
-# When tls_emulation is enabled, this controls how often (per client IP)
-# to send the complete emulated certificate chain.
-#
-# > 0: Subsequent connections within TTL seconds get a smaller cached version.
-#       Saves bandwidth but creates a detectable size difference between
-#       first and repeat connections.
-#
-# = 0: Every connection gets the full certificate. More bandwidth but
-#       perfectly consistent behavior, no anomalies for DPI to detect.
-# ------------------------------------------------------------------------------
-
-tls_full_cert_ttl_secs = 0
-
-# ------------------------------------------------------------------------------
-# ALPN Enforcement
-# Ensure ServerHello responds with the exact ALPN protocol the client requested.
-# Mismatched ALPN (e.g., client asks h2, server says http/1.1) is a DPI red flag.
-# ------------------------------------------------------------------------------
-
-alpn_enforce = true
-
-
-# ==============================================================================
-# ACCESS CONTROL & USERS
-# ==============================================================================
-
-[access]
-
-# ------------------------------------------------------------------------------
-# Replay Attack Protection
-# DPI can record a legitimate user's handshake and replay it later to probe
-# whether the server is a proxy. Telemt remembers recent handshake nonces
-# and rejects duplicates.
-# ------------------------------------------------------------------------------
-
-# Number of nonce slots in the replay detection buffer.
-replay_check_len = 65536
-
-# How long (seconds) to remember nonces before expiring them.
-replay_window_secs = 1800
-
-# Allow clients with incorrect system clocks to connect.
-# false = reject clients with significant time skew (more secure)
-# true  = accept anyone regardless of clock (more permissive)
-ignore_time_skew = false
-
-# ------------------------------------------------------------------------------
-# User Secrets
-# Each user needs a unique 32-character hex string as their secret.
-# Generate with: openssl rand -hex 16
-#
-# This secret is embedded in the tg:// link. Anyone with it can connect.
-# Format: username = "hex_secret"
-# ------------------------------------------------------------------------------
-
-[access.users]
-# alice = "0123456789abcdef0123456789abcdef"
-# bob = "fedcba9876543210fedcba9876543210"
-
-# ------------------------------------------------------------------------------
-# Per-User Connection Limits
-# Limits concurrent TCP connections per user to prevent secret sharing.
-# Uncomment and set for each user as needed.
-# ------------------------------------------------------------------------------
-
-[access.user_max_tcp_conns]
-# alice = 100
-# bob = 50
-
-# ------------------------------------------------------------------------------
-# Per-User Expiration Dates
-# Automatically revoke access after the specified date (ISO 8601 format).
-# ------------------------------------------------------------------------------
-
-[access.user_expirations]
-# alice = "2025-12-31T23:59:59Z"
-# bob = "2026-06-15T00:00:00Z"
-
-# ------------------------------------------------------------------------------
-# Per-User Data Quotas
-# Maximum total bytes transferred per user. Connection refused after limit.
-# ------------------------------------------------------------------------------
-
-[access.user_data_quota]
-# alice = 107374182400
-# bob = 53687091200
-
-# ------------------------------------------------------------------------------
-# Per-User Unique IP Limits
-# Maximum number of different IP addresses that can use this secret
-# at the same time. Highly effective against secret leaking/sharing.
-# Set to 1 for single-device, 2-3 for phone+desktop, etc.
-# ------------------------------------------------------------------------------
-
-[access.user_max_unique_ips]
-# alice = 3
-# bob = 2
-
-
-# ==============================================================================
-# UPSTREAM ROUTING
-# Controls how Telemt connects to Telegram servers (or ME servers).
-# If omitted entirely, uses the OS default route.
-# ==============================================================================
-
-# ------------------------------------------------------------------------------
-# Direct upstream: use the server's own network interface.
-# You can optionally bind to a specific interface or local IP.
-# ------------------------------------------------------------------------------
-
-# [[upstreams]]
-# type = "direct"
-# interface = "eth0"
-# bind_addresses = ["192.0.2.10"]
-# weight = 1
-# enabled = true
-# scopes = "*"
-
-# ------------------------------------------------------------------------------
-# SOCKS5 upstream: route Telegram traffic through a SOCKS5 proxy.
-# Useful if your server's IP is blocked from reaching Telegram DCs.
-# ------------------------------------------------------------------------------
-
-# [[upstreams]]
-# type = "socks5"
-# address = "198.51.100.30:1080"
-# username = "proxy-user"
-# password = "proxy-pass"
-# weight = 1
-# enabled = true
-
-
-# ==============================================================================
-# DATACENTER OVERRIDES
-# Force specific DC IDs to route to specific IP:Port combinations.
-# DC 203 (CDN) is auto-injected by Telemt if not specified here.
-# ==============================================================================
-
-# [dc_overrides]
-# "201" = "149.154.175.50:443"
-# "202" = ["149.154.167.51:443", "149.154.175.100:443"]

config.toml

@@ -4,7 +4,7 @@
 
 # === General Settings ===
 [general]
-use_middle_proxy = false
+use_middle_proxy = true
 # Global ad_tag fallback when user has no per-user tag in [access.user_ad_tags]
 # ad_tag = "00000000000000000000000000000000"
 # Per-user ad_tag in [access.user_ad_tags] (32 hex from @MTProxybot)
@@ -32,6 +32,7 @@ show = "*"
 port = 443
 # proxy_protocol = false           # Enable if behind HAProxy/nginx with PROXY protocol
 # metrics_port = 9090
+# metrics_listen = "0.0.0.0:9090"  # Listen address for metrics (overrides metrics_port)
 # metrics_whitelist = ["127.0.0.1", "::1", "0.0.0.0/0"]
 
 [server.api]

contrib/openbsd/telemt.rcd

@@ -0,0 +1,16 @@
+#!/bin/ksh
+# /etc/rc.d/telemt
+#
+# rc.d(8) script for Telemt MTProxy daemon.
+# Tokio runtime does not daemonize itself, so rc_bg=YES is used.
+
+daemon="/usr/local/bin/telemt"
+daemon_user="_telemt"
+daemon_flags="/etc/telemt/config.toml"
+
+. /etc/rc.d/rc.subr
+
+rc_bg=YES
+rc_reload=NO
+
+rc_cmd $1

contrib/systemd/system-user-telemt.conf

@@ -0,0 +1,3 @@
+u telemt - "telemt user" /var/lib/telemt -
+g telemt - -
+m telemt telemt

contrib/systemd/telemt.service

@@ -0,0 +1,21 @@
+[Unit]
+Description=Telemt
+Wants=network-online.target
+After=multi-user.target network.target network-online.target
+
+[Service]
+Type=simple
+User=telemt
+Group=telemt
+WorkingDirectory=/var/lib/telemt
+ExecStart=/usr/bin/telemt /etc/telemt/telemt.toml
+Restart=on-failure
+RestartSec=10
+LimitNOFILE=65536
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+NoNewPrivileges=true
+
+
+[Install]
+WantedBy=multi-user.target

contrib/systemd/tmpfiles-telemt.conf

@@ -0,0 +1 @@
+d /var/lib/telemt 700 telemt telemt

docs/API.md

@@ -85,6 +85,7 @@ Notes:
 | `GET` | `/v1/health` | none | `200` | `HealthData` |
 | `GET` | `/v1/system/info` | none | `200` | `SystemInfoData` |
 | `GET` | `/v1/runtime/gates` | none | `200` | `RuntimeGatesData` |
+| `GET` | `/v1/runtime/initialization` | none | `200` | `RuntimeInitializationData` |
 | `GET` | `/v1/limits/effective` | none | `200` | `EffectiveLimitsData` |
 | `GET` | `/v1/security/posture` | none | `200` | `SecurityPostureData` |
 | `GET` | `/v1/security/whitelist` | none | `200` | `SecurityWhitelistData` |
@@ -98,6 +99,7 @@ Notes:
 | `GET` | `/v1/runtime/me_quality` | none | `200` | `RuntimeMeQualityData` |
 | `GET` | `/v1/runtime/upstream_quality` | none | `200` | `RuntimeUpstreamQualityData` |
 | `GET` | `/v1/runtime/nat_stun` | none | `200` | `RuntimeNatStunData` |
+| `GET` | `/v1/runtime/me-selftest` | none | `200` | `RuntimeMeSelftestData` |
 | `GET` | `/v1/runtime/connections/summary` | none | `200` | `RuntimeEdgeConnectionsSummaryData` |
 | `GET` | `/v1/runtime/events/recent` | none | `200` | `RuntimeEdgeEventsData` |
 | `GET` | `/v1/stats/users` | none | `200` | `UserInfo[]` |
@@ -147,6 +149,12 @@ Notes:
 - `PATCH` updates only provided fields and does not support explicit clearing of optional fields.
 - `If-Match` supports both quoted and unquoted values; surrounding whitespace is trimmed.
 
+## Query Parameters
+
+| Endpoint | Query | Behavior |
+| --- | --- | --- |
+| `GET /v1/runtime/events/recent` | `limit=<usize>` | Optional. Invalid/missing value falls back to default `50`. Effective value is clamped to `[1, 1000]` and additionally bounded by ring-buffer capacity. |
+
 ## Request Contracts
 
 ### `CreateUserRequest`
@@ -219,6 +227,45 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `me_runtime_ready` | `bool` | Current ME runtime readiness status used for conditional gate decisions. |
 | `me2dc_fallback_enabled` | `bool` | Whether ME -> direct fallback is enabled. |
 | `use_middle_proxy` | `bool` | Current transport mode preference. |
+| `startup_status` | `string` | Startup status (`pending`, `initializing`, `ready`, `failed`, `skipped`). |
+| `startup_stage` | `string` | Current startup stage identifier. |
+| `startup_progress_pct` | `f64` | Startup progress percentage (`0..100`). |
+
+### `RuntimeInitializationData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `status` | `string` | Startup status (`pending`, `initializing`, `ready`, `failed`, `skipped`). |
+| `degraded` | `bool` | Whether runtime is currently in degraded mode. |
+| `current_stage` | `string` | Current startup stage identifier. |
+| `progress_pct` | `f64` | Overall startup progress percentage (`0..100`). |
+| `started_at_epoch_secs` | `u64` | Process start timestamp (Unix seconds). |
+| `ready_at_epoch_secs` | `u64?` | Timestamp when startup reached ready state; absent until ready. |
+| `total_elapsed_ms` | `u64` | Elapsed startup duration in milliseconds. |
+| `transport_mode` | `string` | Startup transport mode (`middle_proxy` or `direct`). |
+| `me` | `RuntimeInitializationMeData` | ME startup substate snapshot. |
+| `components` | `RuntimeInitializationComponentData[]` | Per-component startup timeline and status. |
+
+#### `RuntimeInitializationMeData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `status` | `string` | ME startup status (`pending`, `initializing`, `ready`, `failed`, `skipped`). |
+| `current_stage` | `string` | Current ME startup stage identifier. |
+| `progress_pct` | `f64` | ME startup progress percentage (`0..100`). |
+| `init_attempt` | `u32` | Current ME init attempt counter. |
+| `retry_limit` | `string` | Retry limit (`"unlimited"` or numeric string). |
+| `last_error` | `string?` | Last ME initialization error text when present. |
+
+#### `RuntimeInitializationComponentData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Startup component identifier. |
+| `title` | `string` | Human-readable component title. |
+| `status` | `string` | Component status (`pending`, `running`, `ready`, `failed`, `skipped`). |
+| `started_at_epoch_ms` | `u64?` | Component start timestamp in Unix milliseconds. |
+| `finished_at_epoch_ms` | `u64?` | Component finish timestamp in Unix milliseconds. |
+| `duration_ms` | `u64?` | Component duration in milliseconds. |
+| `attempts` | `u32` | Attempt counter for this component. |
+| `details` | `string?` | Optional short status details text. |
 
 ### `EffectiveLimitsData`
 | Field | Type | Description |
@@ -256,11 +303,22 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `floor_mode` | `string` | Effective floor mode (`static` or `adaptive`). |
 | `adaptive_floor_idle_secs` | `u64` | Adaptive floor idle threshold. |
 | `adaptive_floor_min_writers_single_endpoint` | `u8` | Adaptive floor minimum for single-endpoint DCs. |
+| `adaptive_floor_min_writers_multi_endpoint` | `u8` | Adaptive floor minimum for multi-endpoint DCs. |
 | `adaptive_floor_recover_grace_secs` | `u64` | Adaptive floor recovery grace period. |
+| `adaptive_floor_writers_per_core_total` | `u16` | Target total writers-per-core budget in adaptive mode. |
+| `adaptive_floor_cpu_cores_override` | `u16` | Manual CPU core override (`0` means auto-detect). |
+| `adaptive_floor_max_extra_writers_single_per_core` | `u16` | Extra per-core adaptive headroom for single-endpoint DCs. |
+| `adaptive_floor_max_extra_writers_multi_per_core` | `u16` | Extra per-core adaptive headroom for multi-endpoint DCs. |
+| `adaptive_floor_max_active_writers_per_core` | `u16` | Active writer cap per CPU core. |
+| `adaptive_floor_max_warm_writers_per_core` | `u16` | Warm writer cap per CPU core. |
+| `adaptive_floor_max_active_writers_global` | `u32` | Global active writer cap. |
+| `adaptive_floor_max_warm_writers_global` | `u32` | Global warm writer cap. |
 | `reconnect_max_concurrent_per_dc` | `u32` | Max concurrent reconnects per DC. |
 | `reconnect_backoff_base_ms` | `u64` | Reconnect base backoff. |
 | `reconnect_backoff_cap_ms` | `u64` | Reconnect backoff cap. |
 | `reconnect_fast_retry_count` | `u32` | Number of fast retries before standard backoff strategy. |
+| `writer_pick_mode` | `string` | Writer picker mode (`sorted_rr`, `p2c`). |
+| `writer_pick_sample_size` | `u8` | Candidate sample size for `p2c` picker mode. |
 | `me2dc_fallback` | `bool` | Effective ME -> direct fallback flag. |
 
 #### `EffectiveUserIpPolicyLimits`
@@ -290,16 +348,353 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `entries_total` | `usize` | Number of whitelist CIDR entries. |
 | `entries` | `string[]` | Whitelist CIDR entries as strings. |
 
-### Runtime Min Endpoints
-- `/v1/runtime/me_pool_state`: generations, hardswap state, writer contour/health counts, refill inflight snapshot.
-- `/v1/runtime/me_quality`: ME error/drift/reconnect counters and per-DC RTT coverage snapshot.
-- `/v1/runtime/upstream_quality`: upstream runtime policy, connect counters, health summary and per-upstream DC latency/IP preference.
-- `/v1/runtime/nat_stun`: NAT/STUN runtime flags, server lists, reflection cache state and backoff remaining.
+### `RuntimeMePoolStateData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Runtime payload availability. |
+| `reason` | `string?` | `source_unavailable` when ME pool snapshot is unavailable. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeMePoolStatePayload?` | Null when unavailable. |
 
-### Runtime Edge Endpoints
-- `/v1/runtime/connections/summary`: cached connection totals (`total/me/direct`), active users and top-N users by connections/traffic.
-- `/v1/runtime/events/recent?limit=N`: bounded control-plane ring-buffer events (`limit` clamped to `[1, 1000]`).
-- If `server.api.runtime_edge_enabled=false`, runtime edge endpoints return `enabled=false` with `reason=feature_disabled`.
+#### `RuntimeMePoolStatePayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `generations` | `RuntimeMePoolStateGenerationData` | Active/warm/pending/draining generation snapshot. |
+| `hardswap` | `RuntimeMePoolStateHardswapData` | Hardswap state flags. |
+| `writers` | `RuntimeMePoolStateWriterData` | Writer total/contour/health counters. |
+| `refill` | `RuntimeMePoolStateRefillData` | In-flight refill counters by DC/family. |
+
+#### `RuntimeMePoolStateGenerationData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `active_generation` | `u64` | Active pool generation id. |
+| `warm_generation` | `u64` | Warm pool generation id. |
+| `pending_hardswap_generation` | `u64` | Pending hardswap generation id (`0` when none). |
+| `pending_hardswap_age_secs` | `u64?` | Age of pending hardswap generation in seconds. |
+| `draining_generations` | `u64[]` | Distinct generation ids currently draining. |
+
+#### `RuntimeMePoolStateHardswapData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Hardswap feature toggle. |
+| `pending` | `bool` | `true` when pending generation is non-zero. |
+
+#### `RuntimeMePoolStateWriterData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `total` | `usize` | Total writer rows in snapshot. |
+| `alive_non_draining` | `usize` | Alive writers excluding draining ones. |
+| `draining` | `usize` | Writers marked draining. |
+| `degraded` | `usize` | Non-draining degraded writers. |
+| `contour` | `RuntimeMePoolStateWriterContourData` | Counts by contour state. |
+| `health` | `RuntimeMePoolStateWriterHealthData` | Counts by health bucket. |
+
+#### `RuntimeMePoolStateWriterContourData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `warm` | `usize` | Writers in warm contour. |
+| `active` | `usize` | Writers in active contour. |
+| `draining` | `usize` | Writers in draining contour. |
+
+#### `RuntimeMePoolStateWriterHealthData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `healthy` | `usize` | Non-draining non-degraded writers. |
+| `degraded` | `usize` | Non-draining degraded writers. |
+| `draining` | `usize` | Draining writers. |
+
+#### `RuntimeMePoolStateRefillData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `inflight_endpoints_total` | `usize` | Total in-flight endpoint refill operations. |
+| `inflight_dc_total` | `usize` | Number of distinct DC+family keys with refill in flight. |
+| `by_dc` | `RuntimeMePoolStateRefillDcData[]` | Per-DC refill rows. |
+
+#### `RuntimeMePoolStateRefillDcData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `dc` | `i16` | Telegram DC id. |
+| `family` | `string` | Address family label (`V4`, `V6`). |
+| `inflight` | `usize` | In-flight refill operations for this row. |
+
+### `RuntimeMeQualityData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Runtime payload availability. |
+| `reason` | `string?` | `source_unavailable` when ME pool snapshot is unavailable. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeMeQualityPayload?` | Null when unavailable. |
+
+#### `RuntimeMeQualityPayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `counters` | `RuntimeMeQualityCountersData` | Key ME lifecycle/error counters. |
+| `route_drops` | `RuntimeMeQualityRouteDropData` | Route drop counters by reason. |
+| `dc_rtt` | `RuntimeMeQualityDcRttData[]` | Per-DC RTT and writer coverage rows. |
+
+#### `RuntimeMeQualityCountersData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `idle_close_by_peer_total` | `u64` | Peer-initiated idle closes. |
+| `reader_eof_total` | `u64` | Reader EOF events. |
+| `kdf_drift_total` | `u64` | KDF drift detections. |
+| `kdf_port_only_drift_total` | `u64` | KDF port-only drift detections. |
+| `reconnect_attempt_total` | `u64` | Reconnect attempts. |
+| `reconnect_success_total` | `u64` | Successful reconnects. |
+
+#### `RuntimeMeQualityRouteDropData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `no_conn_total` | `u64` | Route drops with no connection mapping. |
+| `channel_closed_total` | `u64` | Route drops because destination channel is closed. |
+| `queue_full_total` | `u64` | Route drops due queue backpressure (aggregate). |
+| `queue_full_base_total` | `u64` | Route drops in base-queue path. |
+| `queue_full_high_total` | `u64` | Route drops in high-priority queue path. |
+
+#### `RuntimeMeQualityDcRttData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `dc` | `i16` | Telegram DC id. |
+| `rtt_ema_ms` | `f64?` | RTT EMA for this DC. |
+| `alive_writers` | `usize` | Alive writers currently mapped to this DC. |
+| `required_writers` | `usize` | Target writer floor for this DC. |
+| `coverage_pct` | `f64` | `alive_writers / required_writers * 100`. |
+
+### `RuntimeUpstreamQualityData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Runtime payload availability. |
+| `reason` | `string?` | `source_unavailable` when upstream runtime snapshot is unavailable. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `policy` | `RuntimeUpstreamQualityPolicyData` | Effective upstream policy values. |
+| `counters` | `RuntimeUpstreamQualityCountersData` | Upstream connect counters. |
+| `summary` | `RuntimeUpstreamQualitySummaryData?` | Aggregate runtime health summary. |
+| `upstreams` | `RuntimeUpstreamQualityUpstreamData[]?` | Per-upstream runtime rows. |
+
+#### `RuntimeUpstreamQualityPolicyData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `connect_retry_attempts` | `u32` | Upstream connect retry attempts. |
+| `connect_retry_backoff_ms` | `u64` | Upstream retry backoff delay. |
+| `connect_budget_ms` | `u64` | Total connect wall-clock budget. |
+| `unhealthy_fail_threshold` | `u32` | Consecutive fail threshold for unhealthy marking. |
+| `connect_failfast_hard_errors` | `bool` | Whether hard errors skip retries. |
+
+#### `RuntimeUpstreamQualityCountersData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `connect_attempt_total` | `u64` | Total connect attempts. |
+| `connect_success_total` | `u64` | Successful connects. |
+| `connect_fail_total` | `u64` | Failed connects. |
+| `connect_failfast_hard_error_total` | `u64` | Fail-fast hard errors. |
+
+#### `RuntimeUpstreamQualitySummaryData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `configured_total` | `usize` | Total configured upstream entries. |
+| `healthy_total` | `usize` | Upstreams currently healthy. |
+| `unhealthy_total` | `usize` | Upstreams currently unhealthy. |
+| `direct_total` | `usize` | Direct-route upstream entries. |
+| `socks4_total` | `usize` | SOCKS4 upstream entries. |
+| `socks5_total` | `usize` | SOCKS5 upstream entries. |
+
+#### `RuntimeUpstreamQualityUpstreamData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `upstream_id` | `usize` | Runtime upstream index. |
+| `route_kind` | `string` | `direct`, `socks4`, `socks5`. |
+| `address` | `string` | Upstream address (`direct` literal for direct route kind). |
+| `weight` | `u16` | Selection weight. |
+| `scopes` | `string` | Configured scope selector. |
+| `healthy` | `bool` | Current health flag. |
+| `fails` | `u32` | Consecutive fail counter. |
+| `last_check_age_secs` | `u64` | Seconds since last health update. |
+| `effective_latency_ms` | `f64?` | Effective latency score used by selector. |
+| `dc` | `RuntimeUpstreamQualityDcData[]` | Per-DC runtime rows. |
+
+#### `RuntimeUpstreamQualityDcData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `dc` | `i16` | Telegram DC id. |
+| `latency_ema_ms` | `f64?` | Per-DC latency EMA. |
+| `ip_preference` | `string` | `unknown`, `prefer_v4`, `prefer_v6`, `both_work`, `unavailable`. |
+
+### `RuntimeNatStunData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Runtime payload availability. |
+| `reason` | `string?` | `source_unavailable` when shared STUN state is unavailable. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeNatStunPayload?` | Null when unavailable. |
+
+#### `RuntimeNatStunPayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `flags` | `RuntimeNatStunFlagsData` | NAT probe runtime flags. |
+| `servers` | `RuntimeNatStunServersData` | Configured/live STUN server lists. |
+| `reflection` | `RuntimeNatStunReflectionBlockData` | Reflection cache data for v4/v6. |
+| `stun_backoff_remaining_ms` | `u64?` | Remaining retry backoff (milliseconds). |
+
+#### `RuntimeNatStunFlagsData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `nat_probe_enabled` | `bool` | Current NAT probe enable state. |
+| `nat_probe_disabled_runtime` | `bool` | Runtime disable flag due failures/conditions. |
+| `nat_probe_attempts` | `u8` | Configured NAT probe attempt count. |
+
+#### `RuntimeNatStunServersData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `configured` | `string[]` | Configured STUN server entries. |
+| `live` | `string[]` | Runtime live STUN server entries. |
+| `live_total` | `usize` | Number of live STUN entries. |
+
+#### `RuntimeNatStunReflectionBlockData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `v4` | `RuntimeNatStunReflectionData?` | IPv4 reflection data. |
+| `v6` | `RuntimeNatStunReflectionData?` | IPv6 reflection data. |
+
+#### `RuntimeNatStunReflectionData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `addr` | `string` | Reflected public endpoint (`ip:port`). |
+| `age_secs` | `u64` | Reflection value age in seconds. |
+
+### `RuntimeMeSelftestData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Runtime payload availability. |
+| `reason` | `string?` | `source_unavailable` when ME pool is unavailable. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeMeSelftestPayload?` | Null when unavailable. |
+
+#### `RuntimeMeSelftestPayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `kdf` | `RuntimeMeSelftestKdfData` | KDF EWMA health state. |
+| `timeskew` | `RuntimeMeSelftestTimeskewData` | Date-header skew health state. |
+| `ip` | `RuntimeMeSelftestIpData` | Interface IP family classification. |
+| `pid` | `RuntimeMeSelftestPidData` | Process PID marker (`one|non-one`). |
+| `bnd` | `RuntimeMeSelftestBndData` | SOCKS BND.ADDR/BND.PORT health state. |
+
+#### `RuntimeMeSelftestKdfData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `state` | `string` | `ok` or `error` based on EWMA threshold. |
+| `ewma_errors_per_min` | `f64` | EWMA KDF error rate per minute. |
+| `threshold_errors_per_min` | `f64` | Threshold used for `error` decision. |
+| `errors_total` | `u64` | Total source errors (`kdf_drift + socks_kdf_strict_reject`). |
+
+#### `RuntimeMeSelftestTimeskewData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `state` | `string` | `ok` or `error` (`max_skew_secs_15m > 60` => `error`). |
+| `max_skew_secs_15m` | `u64?` | Maximum observed skew in the last 15 minutes. |
+| `samples_15m` | `usize` | Number of skew samples in the last 15 minutes. |
+| `last_skew_secs` | `u64?` | Latest observed skew value. |
+| `last_source` | `string?` | Latest skew source marker. |
+| `last_seen_age_secs` | `u64?` | Age of the latest skew sample. |
+
+#### `RuntimeMeSelftestIpData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `v4` | `RuntimeMeSelftestIpFamilyData?` | IPv4 interface probe result; absent when unknown. |
+| `v6` | `RuntimeMeSelftestIpFamilyData?` | IPv6 interface probe result; absent when unknown. |
+
+#### `RuntimeMeSelftestIpFamilyData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `addr` | `string` | Detected interface IP. |
+| `state` | `string` | `good`, `bogon`, or `loopback`. |
+
+#### `RuntimeMeSelftestPidData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `pid` | `u32` | Current process PID. |
+| `state` | `string` | `one` when PID=1, otherwise `non-one`. |
+
+#### `RuntimeMeSelftestBndData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `addr_state` | `string` | `ok`, `bogon`, or `error`. |
+| `port_state` | `string` | `ok`, `zero`, or `error`. |
+| `last_addr` | `string?` | Latest observed SOCKS BND address. |
+| `last_seen_age_secs` | `u64?` | Age of latest BND sample. |
+
+### `RuntimeEdgeConnectionsSummaryData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Endpoint availability under `runtime_edge_enabled`. |
+| `reason` | `string?` | `feature_disabled` or `source_unavailable`. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeEdgeConnectionsSummaryPayload?` | Null when unavailable. |
+
+#### `RuntimeEdgeConnectionsSummaryPayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `cache` | `RuntimeEdgeConnectionCacheData` | Runtime edge cache metadata. |
+| `totals` | `RuntimeEdgeConnectionTotalsData` | Connection totals block. |
+| `top` | `RuntimeEdgeConnectionTopData` | Top-N leaderboard blocks. |
+| `telemetry` | `RuntimeEdgeConnectionTelemetryData` | Telemetry-policy flags for counters. |
+
+#### `RuntimeEdgeConnectionCacheData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `ttl_ms` | `u64` | Configured cache TTL in milliseconds. |
+| `served_from_cache` | `bool` | `true` when payload is served from cache. |
+| `stale_cache_used` | `bool` | `true` when stale cache is used because recompute is busy. |
+
+#### `RuntimeEdgeConnectionTotalsData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `current_connections` | `u64` | Current global live connections. |
+| `current_connections_me` | `u64` | Current live connections routed through ME. |
+| `current_connections_direct` | `u64` | Current live connections routed through direct path. |
+| `active_users` | `usize` | Users with `current_connections > 0`. |
+
+#### `RuntimeEdgeConnectionTopData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `limit` | `usize` | Effective Top-N row count. |
+| `by_connections` | `RuntimeEdgeConnectionUserData[]` | Users sorted by current connections. |
+| `by_throughput` | `RuntimeEdgeConnectionUserData[]` | Users sorted by cumulative octets. |
+
+#### `RuntimeEdgeConnectionUserData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `username` | `string` | Username. |
+| `current_connections` | `u64` | Current live connections for user. |
+| `total_octets` | `u64` | Cumulative (`client->proxy + proxy->client`) octets. |
+
+#### `RuntimeEdgeConnectionTelemetryData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `user_enabled` | `bool` | Per-user telemetry enable flag. |
+| `throughput_is_cumulative` | `bool` | Always `true` in current implementation. |
+
+### `RuntimeEdgeEventsData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Endpoint availability under `runtime_edge_enabled`. |
+| `reason` | `string?` | `feature_disabled` when endpoint is disabled. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeEdgeEventsPayload?` | Null when unavailable. |
+
+#### `RuntimeEdgeEventsPayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `capacity` | `usize` | Effective ring-buffer capacity. |
+| `dropped_total` | `u64` | Count of dropped oldest events due capacity pressure. |
+| `events` | `ApiEventRecord[]` | Recent events in chronological order. |
+
+#### `ApiEventRecord`
+| Field | Type | Description |
+| --- | --- | --- |
+| `seq` | `u64` | Monotonic sequence number. |
+| `ts_epoch_secs` | `u64` | Event timestamp (Unix seconds). |
+| `event_type` | `string` | Event kind identifier. |
+| `context` | `string` | Context text (truncated to implementation-defined max length). |
 
 ### `ZeroAllData`
 | Field | Type | Description |
@@ -485,7 +880,27 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `floor_mode` | `string` | Writer floor mode. |
 | `adaptive_floor_idle_secs` | `u64` | Idle threshold for adaptive floor. |
 | `adaptive_floor_min_writers_single_endpoint` | `u8` | Minimum writers for single-endpoint DC in adaptive mode. |
+| `adaptive_floor_min_writers_multi_endpoint` | `u8` | Minimum writers for multi-endpoint DC in adaptive mode. |
 | `adaptive_floor_recover_grace_secs` | `u64` | Grace period for floor recovery. |
+| `adaptive_floor_writers_per_core_total` | `u16` | Target total writers-per-core budget in adaptive mode. |
+| `adaptive_floor_cpu_cores_override` | `u16` | CPU core override (`0` means auto-detect). |
+| `adaptive_floor_max_extra_writers_single_per_core` | `u16` | Extra single-endpoint writers budget per core. |
+| `adaptive_floor_max_extra_writers_multi_per_core` | `u16` | Extra multi-endpoint writers budget per core. |
+| `adaptive_floor_max_active_writers_per_core` | `u16` | Active writer cap per core. |
+| `adaptive_floor_max_warm_writers_per_core` | `u16` | Warm writer cap per core. |
+| `adaptive_floor_max_active_writers_global` | `u32` | Global active writer cap. |
+| `adaptive_floor_max_warm_writers_global` | `u32` | Global warm writer cap. |
+| `adaptive_floor_cpu_cores_detected` | `u32` | Runtime-detected CPU cores. |
+| `adaptive_floor_cpu_cores_effective` | `u32` | Effective core count used for adaptive caps. |
+| `adaptive_floor_global_cap_raw` | `u64` | Raw global cap before clamping. |
+| `adaptive_floor_global_cap_effective` | `u64` | Effective global cap after clamping. |
+| `adaptive_floor_target_writers_total` | `u64` | Current adaptive total writer target. |
+| `adaptive_floor_active_cap_configured` | `u64` | Configured global active cap. |
+| `adaptive_floor_active_cap_effective` | `u64` | Effective global active cap. |
+| `adaptive_floor_warm_cap_configured` | `u64` | Configured global warm cap. |
+| `adaptive_floor_warm_cap_effective` | `u64` | Effective global warm cap. |
+| `adaptive_floor_active_writers_current` | `u64` | Current active writers count. |
+| `adaptive_floor_warm_writers_current` | `u64` | Current warm writers count. |
 | `me_keepalive_enabled` | `bool` | ME keepalive toggle. |
 | `me_keepalive_interval_secs` | `u64` | Keepalive period. |
 | `me_keepalive_jitter_secs` | `u64` | Keepalive jitter. |
@@ -507,6 +922,8 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `me_single_endpoint_outage_backoff_max_ms` | `u64` | Outage mode max reconnect backoff. |
 | `me_single_endpoint_shadow_rotate_every_secs` | `u64` | Shadow rotation interval. |
 | `me_deterministic_writer_sort` | `bool` | Deterministic writer ordering toggle. |
+| `me_writer_pick_mode` | `string` | Writer picker mode (`sorted_rr`, `p2c`). |
+| `me_writer_pick_sample_size` | `u8` | Candidate sample size for `p2c` picker mode. |
 | `me_socks_kdf_policy` | `string` | Current SOCKS KDF policy mode. |
 | `quarantined_endpoints_total` | `usize` | Total quarantined endpoints. |
 | `quarantined_endpoints` | `MinimalQuarantineData[]` | Quarantine details. |
@@ -572,14 +989,25 @@ Note: the request contract is defined, but the corresponding route currently ret
 | --- | --- | --- |
 | `dc` | `i16` | Telegram DC id. |
 | `endpoints` | `string[]` | Endpoints in this DC (`ip:port`). |
+| `endpoint_writers` | `DcEndpointWriters[]` | Active writer counts grouped by endpoint. |
 | `available_endpoints` | `usize` | Endpoints currently available in this DC. |
 | `available_pct` | `f64` | `available_endpoints / endpoints_total * 100`. |
 | `required_writers` | `usize` | Required writer count for this DC. |
+| `floor_min` | `usize` | Floor lower bound for this DC. |
+| `floor_target` | `usize` | Floor target writer count for this DC. |
+| `floor_max` | `usize` | Floor upper bound for this DC. |
+| `floor_capped` | `bool` | `true` when computed floor target was capped by active limits. |
 | `alive_writers` | `usize` | Alive writers in this DC. |
 | `coverage_pct` | `f64` | `alive_writers / required_writers * 100`. |
 | `rtt_ms` | `f64?` | Aggregated RTT for DC. |
 | `load` | `usize` | Active client sessions bound to this DC. |
 
+#### `DcEndpointWriters`
+| Field | Type | Description |
+| --- | --- | --- |
+| `endpoint` | `string` | Endpoint (`ip:port`). |
+| `active_writers` | `usize` | Active writers currently mapped to endpoint. |
+
 ### `UserInfo`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -591,6 +1019,9 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `max_unique_ips` | `usize?` | Optional unique IP limit. |
 | `current_connections` | `u64` | Current live connections. |
 | `active_unique_ips` | `usize` | Current active unique source IPs. |
+| `active_unique_ips_list` | `ip[]` | Current active unique source IP list. |
+| `recent_unique_ips` | `usize` | Unique source IP count inside the configured recent window. |
+| `recent_unique_ips_list` | `ip[]` | Recent-window unique source IP list. |
 | `total_octets` | `u64` | Total traffic octets for this user. |
 | `links` | `UserLinks` | Active connection links derived from current config. |
 
@@ -602,11 +1033,15 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `tls` | `string[]` | Active `tg://proxy` links for EE-TLS mode (for each host+TLS domain). |
 
 Link generation uses active config and enabled modes:
-- `[general.links].public_host/public_port` have priority.
-- If `public_host` is not set, startup-detected public IPs are used (`IPv4`, `IPv6`, or both when available).
-- Fallback host sources: listener `announce`, `announce_ip`, explicit listener `ip`.
-- Legacy fallback: `listen_addr_ipv4` and `listen_addr_ipv6` when routable.
-- Startup-detected IPs are fixed for process lifetime and refreshed on restart.
+- Link port is `general.links.public_port` when configured; otherwise `server.port`.
+- If `general.links.public_host` is non-empty, it is used as the single link host override.
+- If `public_host` is not set, hosts are resolved from `server.listeners` in order:
+  `announce` -> `announce_ip` -> listener bind `ip`.
+- For wildcard listener IPs (`0.0.0.0` / `::`), startup-detected external IP of the same family is used when available.
+- Listener-derived hosts are de-duplicated while preserving first-seen order.
+- If multiple hosts are resolved, API returns links for all resolved hosts in every enabled mode.
+- If no host can be resolved from listeners, fallback is startup-detected `IPv4 -> IPv6`.
+- Final compatibility fallback uses `listen_addr_ipv4`/`listen_addr_ipv6` when routable, otherwise `"UNKNOWN"`.
 - User rows are sorted by `username` in ascending lexical order.
 
 ### `CreateUserResponse`
@@ -619,10 +1054,10 @@ Link generation uses active config and enabled modes:
 
 | Endpoint | Notes |
 | --- | --- |
-| `POST /v1/users` | Creates user and validates resulting config before atomic save. |
-| `PATCH /v1/users/{username}` | Partial update of provided fields only. Missing fields remain unchanged. |
+| `POST /v1/users` | Creates user, validates config, then atomically updates only affected `access.*` TOML tables (`access.users` always, plus optional per-user tables present in request). |
+| `PATCH /v1/users/{username}` | Partial update of provided fields only. Missing fields remain unchanged. Current implementation persists full config document on success. |
 | `POST /v1/users/{username}/rotate-secret` | Currently returns `404` in runtime route matcher; request schema is reserved for intended behavior. |
-| `DELETE /v1/users/{username}` | Deletes user and related optional settings. Last user deletion is blocked. |
+| `DELETE /v1/users/{username}` | Deletes only specified user, removes this user from related optional `access.user_*` maps, blocks last-user deletion, and atomically updates only related `access.*` TOML tables. |
 
 All mutating endpoints:
 - Respect `read_only` mode.
@@ -630,6 +1065,10 @@ All mutating endpoints:
 - Return new `revision` after successful write.
 - Use process-local mutation lock + atomic write (`tmp + rename`) for config persistence.
 
+Delete path cleanup guarantees:
+- Config cleanup removes only the requested username keys.
+- Runtime unique-IP cleanup removes only this user's limiter and tracked IP state.
+
 ## Runtime State Matrix
 
 | Endpoint | `minimal_runtime_enabled=false` | `minimal_runtime_enabled=true` + source unavailable | `minimal_runtime_enabled=true` + source available |
@@ -643,6 +1082,28 @@ All mutating endpoints:
 - ME endpoints: ME pool is absent (for example direct-only mode or failed ME initialization).
 - Upstreams endpoint: non-blocking upstream snapshot lock is unavailable at request time.
 
+Additional runtime endpoint behavior:
+
+| Endpoint | Disabled by feature flag | `source_unavailable` condition | Normal mode |
+| --- | --- | --- | --- |
+| `/v1/runtime/me_pool_state` | No | ME pool snapshot unavailable | `enabled=true`, full payload |
+| `/v1/runtime/me_quality` | No | ME pool snapshot unavailable | `enabled=true`, full payload |
+| `/v1/runtime/upstream_quality` | No | Upstream runtime snapshot unavailable | `enabled=true`, full payload |
+| `/v1/runtime/nat_stun` | No | STUN shared state unavailable | `enabled=true`, full payload |
+| `/v1/runtime/me-selftest` | No | ME pool unavailable => `enabled=false`, `reason=source_unavailable` | `enabled=true`, full payload |
+| `/v1/runtime/connections/summary` | `runtime_edge_enabled=false` => `enabled=false`, `reason=feature_disabled` | Recompute lock contention with no cache entry => `enabled=true`, `reason=source_unavailable` | `enabled=true`, full payload |
+| `/v1/runtime/events/recent` | `runtime_edge_enabled=false` => `enabled=false`, `reason=feature_disabled` | Not used in current implementation | `enabled=true`, full payload |
+
+## ME Fallback Behavior Exposed Via API
+
+When `general.use_middle_proxy=true` and `general.me2dc_fallback=true`:
+- Startup does not block on full ME pool readiness; initialization can continue in background.
+- Runtime initialization payload can expose ME stage `background_init` until pool becomes ready.
+- Admission/routing decision uses two readiness grace windows for "ME not ready" periods:
+  `80s` before first-ever readiness is observed (startup grace),
+  `6s` after readiness has been observed at least once (runtime failover timeout).
+- While in fallback window breach, new sessions are routed via Direct-DC; when ME becomes ready, routing returns to Middle mode for new sessions.
+
 ## Serialization Rules
 
 - Success responses always include `revision`.
@@ -650,6 +1111,7 @@ All mutating endpoints:
 - Optional fields with `skip_serializing_if` are omitted when absent.
 - Nullable payload fields may still be `null` where contract uses `?` (for example `UserInfo` option fields).
 - For `/v1/stats/upstreams`, authentication details of SOCKS upstreams are intentionally omitted.
+- `ip[]` fields are serialized as JSON string arrays (for example `"1.2.3.4"`, `"2001:db8::1"`).
 
 ## Operational Notes
 
@@ -665,7 +1127,7 @@ All mutating endpoints:
 | Runtime apply path | Successful writes are picked up by existing config watcher/hot-reload path. |
 | Exposure | Built-in TLS/mTLS is not provided. Use loopback bind + reverse proxy if needed. |
 | Pagination | User list currently has no pagination/filtering. |
-| Serialization side effect | Config comments/manual formatting are not preserved on write. |
+| Serialization side effect | Updated TOML table bodies are re-serialized on write. Endpoints that persist full config can still rewrite broader formatting/comments. |
 
 ## Known Limitations (Current Release)
 

docs/FAQ.en.md

@@ -55,7 +55,10 @@ user2 = "00000000000000000000000000000002"
 user3 = "00000000000000000000000000000003"
 ```
 4. Save the config. Ctrl+S -> Ctrl+X. You don't need to restart telemt.
-5. Get the links via `journalctl -u telemt -n -g "links" --no-pager -o cat | tac`
+5. Get the links via
+```bash
+curl -s http://127.0.0.1:9091/v1/users | jq
+```
 
 ## How to view metrics
 
@@ -80,6 +83,13 @@ To specify a domain in the links, add to the `[general.links]` section of the co
 public_host = "proxy.example.com"
 ```
 
+### Server connection limit
+Limits the total number of open connections to the server:
+```toml
+[server]
+max_connections = 10000    # 0 - unlimited, 10000 - default
+```
+
 ### Upstream Manager
 To specify an upstream, add to the `[[upstreams]]` section of the config.toml file:
 #### Binding to IP

docs/FAQ.ru.md

@@ -55,7 +55,10 @@ user2 = "00000000000000000000000000000002"
 user3 = "00000000000000000000000000000003"
 ```
 4. Сохранить конфиг. Ctrl+S -> Ctrl+X. Перезапускать telemt не нужно.
-5. Получить ссылки через `journalctl -u telemt -n -g "links" --no-pager -o cat | tac`
+5. Получить ссылки через
+```bash
+curl -s http://127.0.0.1:9091/v1/users | jq
+```
 
 ## Как посмотреть метрики
 
@@ -80,6 +83,13 @@ metrics_whitelist = ["127.0.0.1/32", "::1/128", "0.0.0.0/0"]
 public_host = "proxy.example.com"
 ```
 
+### Общий лимит подключений к серверу
+Ограничивает общее число открытых подключений к серверу:
+```toml
+[server]
+max_connections = 10000    # 0 - unlimited, 10000 - default
+```
+
 ### Upstream Manager
 Чтобы указать апстрим, добавьте в секцию `[[upstreams]]` файла config.toml:
 #### Привязка к IP
@@ -110,3 +120,4 @@ password = "pass"          # Password for Auth on SOCKS-server
 weight = 1                 # Set Weight for Scenarios
 enabled = true
 ```
+

docs/LICENSE/LICENSE.de.md

@@ -0,0 +1,92 @@
+# Öffentliche TELEMT-Lizenz 3
+
+***Alle Rechte vorbehalten (c) 2026 Telemt***
+
+Hiermit wird jeder Person, die eine Kopie dieser Software und der dazugehörigen Dokumentation (nachfolgend "Software") erhält, unentgeltlich die Erlaubnis erteilt, die Software ohne Einschränkungen zu nutzen, einschließlich des Rechts, die Software zu verwenden, zu vervielfältigen, zu ändern, abgeleitete Werke zu erstellen, zu verbinden, zu veröffentlichen, zu verbreiten, zu unterlizenzieren und/oder Kopien der Software zu verkaufen sowie diese Rechte auch denjenigen einzuräumen, denen die Software zur Verfügung gestellt wird, vorausgesetzt, dass sämtliche Urheberrechtshinweise sowie die Bedingungen und Bestimmungen dieser Lizenz eingehalten werden.
+
+### Begriffsbestimmungen
+
+Für die Zwecke dieser Lizenz gelten die folgenden Definitionen:
+
+**"Software" (Software)** — die Telemt-Software einschließlich Quellcode, Dokumentation und sämtlicher zugehöriger Dateien, die unter den Bedingungen dieser Lizenz verbreitet werden.
+
+**"Contributor" (Contributor)** — jede natürliche oder juristische Person, die Code, Patches, Dokumentation oder andere Materialien eingereicht hat, die von den Maintainers des Projekts angenommen und in die Software aufgenommen wurden.
+
+**"Beitrag" (Contribution)** — jedes urheberrechtlich geschützte Werk, das bewusst zur Aufnahme in die Software eingereicht wurde.
+
+**"Modifizierte Version" (Modified Version)** — jede Version der Software, die gegenüber der ursprünglichen Software geändert, angepasst, erweitert oder anderweitig modifiziert wurde.
+
+**"Maintainers" (Maintainers)** — natürliche oder juristische Personen, die für das offizielle Telemt-Projekt und dessen offizielle Veröffentlichungen verantwortlich sind.
+
+### 1 Urheberrechtshinweis (Attribution)
+
+Bei der Weitergabe der Software, sowohl in Form des Quellcodes als auch in binärer Form, MÜSSEN folgende Elemente erhalten bleiben:
+
+- der oben genannte Urheberrechtshinweis;
+- der vollständige Text dieser Lizenz;
+- sämtliche bestehenden Hinweise auf Urheberschaft.
+
+### 2 Hinweis auf Modifikationen
+
+Wenn Änderungen an der Software vorgenommen werden, MUSS die Person, die diese Änderungen vorgenommen hat, eindeutig darauf hinweisen, dass die Software modifiziert wurde, und eine kurze Beschreibung der vorgenommenen Änderungen beifügen.
+
+Modifizierte Versionen der Software DÜRFEN NICHT als die originale Version von Telemt dargestellt werden.
+
+### 3 Marken und Bezeichnungen
+
+Diese Lizenz GEWÄHRT KEINE Rechte zur Nutzung der Bezeichnung **"Telemt"**, des Telemt-Logos oder sonstiger Marken, Kennzeichen oder Branding-Elemente von Telemt.
+
+Weiterverbreitete oder modifizierte Versionen der Software DÜRFEN die Bezeichnung Telemt nicht in einer Weise verwenden, die bei Nutzern den Eindruck eines offiziellen Ursprungs oder einer Billigung durch das Telemt-Projekt erwecken könnte, sofern hierfür keine ausdrückliche Genehmigung der Maintainers vorliegt.
+
+Die Verwendung der Bezeichnung **Telemt** zur Beschreibung einer modifizierten Version der Software ist nur zulässig, wenn diese Version eindeutig als modifiziert oder inoffiziell gekennzeichnet ist.
+
+Jegliche Verbreitung, die Nutzer vernünftigerweise darüber täuschen könnte, dass es sich um eine offizielle Veröffentlichung von Telemt handelt, ist untersagt.
+
+### 4 Transparenz bei der Verbreitung von Binärversionen
+
+Im Falle der Verbreitung kompilierter Binärversionen der Software wird der Verbreiter HIERMIT ERMUTIGT (encouraged), soweit dies vernünftigerweise möglich ist, Zugang zum entsprechenden Quellcode sowie zu den Build-Anweisungen bereitzustellen.
+
+Diese Praxis trägt zur Transparenz bei und ermöglicht es Empfängern, die Integrität und Reproduzierbarkeit der verbreiteten Builds zu überprüfen.
+
+## 5 Gewährung einer Patentlizenz und Beendigung von Rechten
+
+Jeder Contributor gewährt den Empfängern der Software eine unbefristete, weltweite, nicht-exklusive, unentgeltliche, lizenzgebührenfreie und unwiderrufliche Patentlizenz für:
+
+- die Herstellung,
+- die Beauftragung der Herstellung,
+- die Nutzung,
+- das Anbieten zum Verkauf,
+- den Verkauf,
+- den Import,
+- sowie jede sonstige Verbreitung der Software.
+
+Diese Patentlizenz erstreckt sich ausschließlich auf solche Patentansprüche, die notwendigerweise durch den jeweiligen Beitrag des Contributors allein oder in Kombination mit der Software verletzt würden.
+
+Leitet eine Person ein Patentverfahren ein oder beteiligt sich daran, einschließlich Gegenklagen oder Kreuzklagen, mit der Behauptung, dass die Software oder ein darin enthaltener Beitrag ein Patent verletzt, **erlöschen sämtliche durch diese Lizenz gewährten Rechte für diese Person unmittelbar mit Einreichung der Klage**.
+
+Darüber hinaus erlöschen alle durch diese Lizenz gewährten Rechte **automatisch**, wenn eine Person ein gerichtliches Verfahren einleitet, in dem behauptet wird, dass die Software selbst ein Patent oder andere Rechte des geistigen Eigentums verletzt.
+
+### 6 Beteiligung und Beiträge zur Entwicklung
+
+Sofern ein Contributor nicht ausdrücklich etwas anderes erklärt, gilt jeder Beitrag, der bewusst zur Aufnahme in die Software eingereicht wird, als unter den Bedingungen dieser Lizenz lizenziert.
+
+Durch die Einreichung eines Beitrags gewährt der Contributor den Maintainers des Telemt-Projekts sowie allen Empfängern der Software die in dieser Lizenz beschriebenen Rechte in Bezug auf diesen Beitrag.
+
+### 7 Urheberhinweis bei Netzwerk- und Servicenutzung
+
+Wird die Software zur Bereitstellung eines öffentlich zugänglichen Netzwerkdienstes verwendet, MUSS der Betreiber dieses Dienstes einen Hinweis auf die Urheberschaft von Telemt an mindestens einer der folgenden Stellen anbringen:
+
+* in der Servicedokumentation;
+* in der Dienstbeschreibung;
+* auf einer Seite "Über" oder einer vergleichbaren Informationsseite;
+* in anderen für Nutzer zugänglichen Materialien, die in angemessenem Zusammenhang mit dem Dienst stehen.
+
+Ein solcher Hinweis DARF NICHT den Eindruck erwecken, dass der Dienst vom Telemt-Projekt oder dessen Maintainers unterstützt oder offiziell gebilligt wird.
+
+### 8 Haftungsausschluss und salvatorische Klausel
+
+DIE SOFTWARE WIRD "WIE BESEHEN" BEREITGESTELLT, OHNE JEGLICHE AUSDRÜCKLICHE ODER STILLSCHWEIGENDE GEWÄHRLEISTUNG, EINSCHLIESSLICH, ABER NICHT BESCHRÄNKT AUF GEWÄHRLEISTUNGEN DER MARKTGÄNGIGKEIT, DER EIGNUNG FÜR EINEN BESTIMMTEN ZWECK UND DER NICHTVERLETZUNG VON RECHTEN.
+
+IN KEINEM FALL HAFTEN DIE AUTOREN ODER RECHTEINHABER FÜR IRGENDWELCHE ANSPRÜCHE, SCHÄDEN ODER SONSTIGE HAFTUNG, DIE AUS VERTRAG, UNERLAUBTER HANDLUNG ODER AUF ANDERE WEISE AUS DER SOFTWARE ODER DER NUTZUNG DER SOFTWARE ENTSTEHEN.
+
+SOLLTE EINE BESTIMMUNG DIESER LIZENZ ALS UNWIRKSAM ODER NICHT DURCHSETZBAR ANGESEHEN WERDEN, IST DIESE BESTIMMUNG SO AUSZULEGEN, DASS SIE DEM URSPRÜNGLICHEN WILLEN DER PARTEIEN MÖGLICHST NAHEKOMMT; DIE ÜBRIGEN BESTIMMUNGEN BLEIBEN DAVON UNBERÜHRT UND IN VOLLER WIRKUNG.

docs/LICENSE/LICENSE.en.md

@@ -0,0 +1,143 @@
+###### TELEMT Public License 3 ######
+##### Copyright (c) 2026 Telemt #####
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this Software and associated documentation files (the "Software"),
+to use, reproduce, modify, prepare derivative works of, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, provided that all
+copyright notices, license terms, and conditions set forth in this License
+are preserved and complied with.
+
+### Official Translations
+
+The canonical version of this License is the English version.
+
+Official translations are provided for informational purposes only
+and for convenience, and do not have legal force. In case of any
+discrepancy, the English version of this License shall prevail.
+
+Available versions:
+- English in Markdown: docs/LICENSE/LICENSE.md
+- German: docs/LICENSE/LICENSE.de.md
+- Russian: docs/LICENSE/LICENSE.ru.md
+
+### Definitions
+
+For the purposes of this License:
+
+"Software" means the Telemt software, including source code, documentation,
+and any associated files distributed under this License.
+
+"Contributor" means any person or entity that submits code, patches,
+documentation, or other contributions to the Software that are accepted
+into the Software by the maintainers.
+
+"Contribution" means any work of authorship intentionally submitted
+to the Software for inclusion in the Software.
+
+"Modified Version" means any version of the Software that has been
+changed, adapted, extended, or otherwise modified from the original
+Software.
+
+"Maintainers" means the individuals or entities responsible for
+the official Telemt project and its releases.
+
+#### 1 Attribution
+
+Redistributions of the Software, in source or binary form, MUST RETAIN the
+above copyright notice, this license text, and any existing attribution
+notices.
+
+#### 2 Modification Notice
+
+If you modify the Software, you MUST clearly state that the Software has been
+modified and include a brief description of the changes made.
+
+Modified versions MUST NOT be presented as the original Telemt.
+
+#### 3 Trademark and Branding
+
+This license DOES NOT grant permission to use the name "Telemt", 
+the Telemt logo, or any Telemt trademarks or branding.
+
+Redistributed or modified versions of the Software MAY NOT use the Telemt
+name in a way that suggests endorsement or official origin without explicit
+permission from the Telemt maintainers.
+
+Use of the name "Telemt" to describe a modified version of the Software
+is permitted only if the modified version is clearly identified as a
+modified or unofficial version.
+
+Any distribution that could reasonably confuse users into believing that
+the software is an official Telemt release is prohibited.
+
+#### 4 Binary Distribution Transparency
+
+If you distribute compiled binaries of the Software,
+you are ENCOURAGED to provide access to the corresponding
+source code and build instructions where reasonably possible.
+
+This helps preserve transparency and allows recipients to verify the
+integrity and reproducibility of distributed builds.
+
+#### 5 Patent Grant and Defensive Termination Clause
+
+Each contributor grants you a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Software.
+
+This patent license applies only to those patent claims necessarily
+infringed by the contributor’s contribution alone or by combination of
+their contribution with the Software.
+
+If you initiate or participate in any patent litigation, including
+cross-claims or counterclaims, alleging that the Software or any
+contribution incorporated within the Software constitutes patent
+infringement, then **all rights granted to you under this license shall
+terminate immediately** as of the date such litigation is filed.
+
+Additionally, if you initiate legal action alleging that the
+Software itself infringes your patent or other intellectual
+property rights, then all rights granted to you under this
+license SHALL TERMINATE automatically.
+
+#### 6 Contributions
+
+Unless you explicitly state otherwise, any Contribution intentionally
+submitted for inclusion in the Software shall be licensed under the terms
+of this License.
+
+By submitting a Contribution, you grant the Telemt maintainers and all
+recipients of the Software the rights described in this License with
+respect to that Contribution.
+
+#### 7 Network Use Attribution
+
+If the Software is used to provide a publicly accessible network service,
+the operator of such service MUST provide attribution to Telemt in at least
+one of the following locations:
+
+- service documentation
+- service description
+- an "About" or similar informational page
+- other user-visible materials reasonably associated with the service
+
+Such attribution MUST NOT imply endorsement by the Telemt project or its
+maintainers.
+
+#### 8 Disclaimer of Warranty and Severability Clause
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE
+
+IF ANY PROVISION OF THIS LICENSE IS HELD TO BE INVALID OR UNENFORCEABLE,
+SUCH PROVISION SHALL BE INTERPRETED TO REFLECT THE ORIGINAL INTENT
+OF THE PARTIES AS CLOSELY AS POSSIBLE, AND THE REMAINING PROVISIONS
+SHALL REMAIN IN FULL FORCE AND EFFECT

docs/LICENSE/LICENSE.ru.md

@@ -0,0 +1,90 @@
+# Публичная лицензия TELEMT 3
+
+***Все права защищёны (c) 2026 Telemt***
+
+Настоящим любому лицу, получившему копию данного программного обеспечения и сопутствующей документации (далее — "Программное обеспечение"), безвозмездно предоставляется разрешение использовать Программное обеспечение без ограничений, включая право использовать, воспроизводить, изменять, создавать производные произведения, объединять, публиковать, распространять, сублицензировать и (или) продавать копии Программного обеспечения, а также предоставлять такие права лицам, которым предоставляется Программное обеспечение, при условии соблюдения всех уведомлений об авторских правах, условий и положений настоящей Лицензии.
+
+### Определения
+
+Для целей настоящей Лицензии применяются следующие определения:
+
+**"Программное обеспечение" (Software)** — программное обеспечение Telemt, включая исходный код, документацию и любые связанные файлы, распространяемые на условиях настоящей Лицензии.
+
+**"Контрибьютор" (Contributor)** — любое физическое или юридическое лицо, направившее код, исправления (патчи), документацию или иные материалы, которые были приняты мейнтейнерами проекта и включены в состав Программного обеспечения.
+
+**"Вклад" (Contribution)** — любое произведение авторского права, намеренно представленное для включения в состав Программного обеспечения.
+
+**"Модифицированная версия" (Modified Version)** — любая версия Программного обеспечения, которая была изменена, адаптирована, расширена или иным образом модифицирована по сравнению с исходным Программным обеспечением.
+
+**"Мейнтейнеры" (Maintainers)** — физические или юридические лица, ответственные за официальный проект Telemt и его официальные релизы.
+
+### 1 Указание авторства
+
+При распространении Программного обеспечения, как в форме исходного кода, так и в бинарной форме, ДОЛЖНЫ СОХРАНЯТЬСЯ:
+
+- указанное выше уведомление об авторских правах;
+- текст настоящей Лицензии;
+- любые существующие уведомления об авторстве.
+
+### 2 Уведомление о модификации
+
+В случае внесения изменений в Программное обеспечение лицо, осуществившее такие изменения, ОБЯЗАНО явно указать, что Программное обеспечение было модифицировано, а также включить краткое описание внесённых изменений.
+
+Модифицированные версии Программного обеспечения НЕ ДОЛЖНЫ представляться как оригинальная версия Telemt.
+
+### 3 Товарные знаки и обозначения
+
+Настоящая Лицензия НЕ ПРЕДОСТАВЛЯЕТ права использовать наименование **"Telemt"**, логотип Telemt, а также любые товарные знаки, фирменные обозначения или элементы бренда Telemt.
+
+Распространяемые или модифицированные версии Программного обеспечения НЕ ДОЛЖНЫ использовать наименование Telemt таким образом, который может создавать у пользователей впечатление официального происхождения либо одобрения со стороны проекта Telemt без явного разрешения мейнтейнеров проекта.
+
+Использование наименования **Telemt** для описания модифицированной версии Программного обеспечения допускается только при условии, что такая версия ясно обозначена как модифицированная или неофициальная.
+
+Запрещается любое распространение, которое может разумно вводить пользователей в заблуждение относительно того, что программное обеспечение является официальным релизом Telemt.
+
+### 4 Прозрачность распространения бинарных версий
+
+В случае распространения скомпилированных бинарных версий Программного обеспечения распространитель НАСТОЯЩИМ ПОБУЖДАЕТСЯ предоставлять доступ к соответствующему исходному коду и инструкциям по сборке, если это разумно возможно.
+
+Такая практика способствует прозрачности распространения и позволяет получателям проверять целостность и воспроизводимость распространяемых сборок.
+
+### 5 Предоставление патентной лицензии и прекращение прав
+
+Каждый контрибьютор предоставляет получателям Программного обеспечения бессрочную, всемирную, неисключительную, безвозмездную, не требующую выплаты роялти и безотзывную патентную лицензию на:
+
+- изготовление,
+- поручение изготовления,
+- использование,
+- предложение к продаже,
+- продажу,
+- импорт,
+- и иное распространение Программного обеспечения.
+
+Такая патентная лицензия распространяется исключительно на те патентные требования, которые неизбежно нарушаются соответствующим вкладом контрибьютора как таковым либо его сочетанием с Программным обеспечением.
+
+Если лицо инициирует либо участвует в каком-либо судебном разбирательстве по патентному спору, включая встречные или перекрёстные иски, утверждая, что Программное обеспечение либо любой вклад, включённый в него, нарушает патент, **все права, предоставленные такому лицу настоящей Лицензией, немедленно прекращаются** с даты подачи соответствующего иска.
+
+Кроме того, если лицо инициирует судебное разбирательство, утверждая, что само Программное обеспечение нарушает его патентные либо иные права интеллектуальной собственности, все права, предоставленные настоящей Лицензией, **автоматически прекращаются**.
+
+### 6 Участие и вклад в разработку
+
+Если контрибьютор явно не указал иное, любой Вклад, намеренно представленный для включения в Программное обеспечение, считается лицензированным на условиях настоящей Лицензии.
+Путём предоставления Вклада контрибьютор предоставляет мейнтейнером проекта Telemt и всем получателям Программного обеспечения права, предусмотренные настоящей Лицензией, в отношении такого Вклада.
+
+### 7 Указание авторства при сетевом и сервисном использовании
+
+В случае использования Программного обеспечения для предоставления публично доступного сетевого сервиса оператор такого сервиса ОБЯЗАН обеспечить указание авторства Telemt как минимум в одном из следующих мест:
+- документация сервиса;
+- описание сервиса;
+- страница "О программе" или аналогичная информационная страница;
+- иные материалы, доступные пользователям и разумно связанные с данным сервисом.
+
+Такое указание авторства НЕ ДОЛЖНО создавать впечатление одобрения или официальной поддержки со стороны проекта Telemt либо его мейнтейнеров.
+
+### 8 Отказ от гарантий и делимость положений
+
+ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ "КАК ЕСТЬ", БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ГАРАНТИЯМИ КОММЕРЧЕСКОЙ ПРИГОДНОСТИ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ.
+
+НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ТРЕБОВАНИЯМ, УБЫТКАМ ИЛИ ИНОЙ ОТВЕТСТВЕННОСТИ, ВОЗНИКАЮЩЕЙ В РЕЗУЛЬТАТЕ ДОГОВОРА, ДЕЛИКТА ИЛИ ИНЫМ ОБРАЗОМ, СВЯЗАННЫМ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ЕГО ИСПОЛЬЗОВАНИЕМ.
+
+В СЛУЧАЕ ЕСЛИ КАКОЕ-ЛИБО ПОЛОЖЕНИЕ НАСТОЯЩЕЙ ЛИЦЕНЗИИ ПРИЗНАЁТСЯ НЕДЕЙСТВИТЕЛЬНЫМ ИЛИ НЕПРИМЕНИМЫМ, ТАКОЕ ПОЛОЖЕНИЕ ПОДЛЕЖИТ ТОЛКОВАНИЮ МАКСИМАЛЬНО БЛИЗКО К ИСХОДНОМУ НАМЕРЕНИЮ СТОРОН, ПРИ ЭТОМ ОСТАЛЬНЫЕ ПОЛОЖЕНИЯ СОХРАНЯЮТ ПОЛНУЮ ЮРИДИЧЕСКУЮ СИЛУ.

docs/OPENBSD.en.md

@@ -0,0 +1,132 @@
+# Telemt on OpenBSD (Build, Run, and rc.d)
+
+This guide covers a practical OpenBSD deployment flow for Telemt:
+- build from source,
+- install binary and config,
+- run as an rc.d daemon,
+- verify basic runtime behavior.
+
+## 1. Prerequisites
+
+Install required packages:
+
+```sh
+doas pkg_add rust git
+```
+
+Notes:
+- Telemt release installer (`install.sh`) is Linux-only.
+- On OpenBSD, use source build with `cargo`.
+
+## 2. Build from source
+
+```sh
+git clone https://github.com/telemt/telemt
+cd telemt
+cargo build --release
+./target/release/telemt --version
+```
+
+For low-RAM systems, this repository already uses `lto = "thin"` in release profile.
+
+## 3. Install binary and config
+
+```sh
+doas install -d -m 0755 /usr/local/bin
+doas install -m 0755 ./target/release/telemt /usr/local/bin/telemt
+
+doas install -d -m 0750 /etc/telemt
+doas install -m 0640 ./config.toml /etc/telemt/config.toml
+```
+
+## 4. Create runtime user
+
+```sh
+doas useradd -L daemon -s /sbin/nologin -d /var/empty _telemt
+```
+
+If `_telemt` already exists, continue.
+
+## 5. Install rc.d service
+
+Install the provided script:
+
+```sh
+doas install -m 0555 ./contrib/openbsd/telemt.rcd /etc/rc.d/telemt
+```
+
+Enable and start:
+
+```sh
+doas rcctl enable telemt
+# Optional: send daemon output to syslog
+#doas rcctl set telemt logger daemon.info
+
+doas rcctl start telemt
+```
+
+Service controls:
+
+```sh
+doas rcctl check telemt
+doas rcctl restart telemt
+doas rcctl stop telemt
+```
+
+## 6. Resource limits (recommended)
+
+OpenBSD rc.d can apply limits via login class. Add class `telemt` and assign it to `_telemt`.
+
+Example class entry:
+
+```text
+telemt:\
+    :openfiles-cur=8192:openfiles-max=16384:\
+    :datasize-cur=768M:datasize-max=1024M:\
+    :coredumpsize=0:\
+    :tc=daemon:
+```
+
+These values are conservative defaults for small and medium deployments.
+Increase `openfiles-*` only if logs show descriptor exhaustion under load.
+
+Then rebuild database and assign class:
+
+```sh
+doas cap_mkdb /etc/login.conf
+#doas usermod -L telemt _telemt
+```
+
+Uncomment `usermod` if you want this class bound to the Telemt user.
+
+## 7. Functional smoke test
+
+1. Validate service state:
+
+```sh
+doas rcctl check telemt
+```
+
+2. Check listener is present (replace 443 if needed):
+
+```sh
+netstat -n -f inet -p tcp | grep LISTEN | grep '\.443'
+```
+
+3. Verify process user:
+
+```sh
+ps -o user,pid,command -ax | grep telemt | grep -v grep
+```
+
+4. If startup fails, debug in foreground:
+
+```sh
+RUST_LOG=debug /usr/local/bin/telemt /etc/telemt/config.toml
+```
+
+## 8. OpenBSD-specific caveats
+
+- OpenBSD does not support per-socket keepalive retries/interval tuning in the same way as Linux.
+- Telemt source already uses target-aware cfg gates for keepalive setup.
+- Use rc.d/rcctl, not systemd.

docs/QUICK_START_GUIDE.en.md

@@ -48,11 +48,16 @@ Save the obtained result somewhere. You will need it later!
 
 ---
 
-**1. Place your config to /etc/telemt.toml**
+**1. Place your config to /etc/telemt/telemt.toml**
+
+Create config directory:
+```bash
+mkdir /etc/telemt
+```
 
 Open nano
 ```bash
-nano /etc/telemt.toml
+nano /etc/telemt/telemt.toml
 ```
 paste your config
 
@@ -67,6 +72,9 @@ classic = false
 secure = false
 tls = true
 
+[server]
+port = 443
+
 [server.api]
 enabled = true
 # listen = "127.0.0.1:9091"
@@ -90,7 +98,14 @@ then Ctrl+S -> Ctrl+X to save
 
 ---
 
-**2. Create service on /etc/systemd/system/telemt.service**
+**2. Create telemt user**
+
+```bash
+useradd -d /opt/telemt -m -r -U telemt
+chown -R telemt:telemt /etc/telemt
+```
+
+**3. Create service on /etc/systemd/system/telemt.service**
 
 Open nano
 ```bash
@@ -101,28 +116,38 @@ paste this Systemd Module
 ```bash
 [Unit]
 Description=Telemt
-After=network.target
+After=network-online.target
+Wants=network-online.target
 
 [Service]
 Type=simple
-WorkingDirectory=/bin
-ExecStart=/bin/telemt /etc/telemt.toml
+User=telemt
+Group=telemt
+WorkingDirectory=/opt/telemt
+ExecStart=/bin/telemt /etc/telemt/telemt.toml
 Restart=on-failure
 LimitNOFILE=65536
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+NoNewPrivileges=true
 
 [Install]
 WantedBy=multi-user.target
 ```
 then Ctrl+S -> Ctrl+X to save
 
+reload systemd units
+```bash
+systemctl daemon-reload
+```
 
-**3.** To start it, enter the command `systemctl start telemt`
+**4.** To start it, enter the command `systemctl start telemt`
 
-**4.** To get status information, enter `systemctl status telemt`
+**5.** To get status information, enter `systemctl status telemt`
 
-**5.** For automatic startup at system boot, enter `systemctl enable telemt`
+**6.** For automatic startup at system boot, enter `systemctl enable telemt`
 
-**6.** To get the link(s), enter
+**7.** To get the link(s), enter
 ```bash
 curl -s http://127.0.0.1:9091/v1/users | jq
 ```

docs/QUICK_START_GUIDE.ru.md

@@ -48,11 +48,16 @@ python3 -c 'import os; print(os.urandom(16).hex())'
 
 ---
 
-**1. Поместите свою конфигурацию в файл /etc/telemt.toml**
+**1. Поместите свою конфигурацию в файл /etc/telemt/telemt.toml**
+
+Создаём директорию для конфига:
+```bash
+mkdir /etc/telemt
+```
 
 Открываем nano
 ```bash
-nano /etc/telemt.toml
+nano /etc/telemt/telemt.toml
 ```
 Вставьте свою конфигурацию
 
@@ -67,6 +72,9 @@ classic = false
 secure = false
 tls = true
 
+[server]
+port = 443
+
 [server.api]
 enabled = true
 # listen = "127.0.0.1:9091"
@@ -90,7 +98,14 @@ hello = "00000000000000000000000000000000"
 
 ---
 
-**2. Создайте службу в /etc/systemd/system/telemt.service**
+**2. Создайте пользователя для telemt**
+
+```bash
+useradd -d /opt/telemt -m -r -U telemt
+chown -R telemt:telemt /etc/telemt
+```
+
+**3. Создайте службу в /etc/systemd/system/telemt.service**
 
 Открываем nano
 ```bash
@@ -101,35 +116,45 @@ nano /etc/systemd/system/telemt.service
 ```bash
 [Unit]
 Description=Telemt
-After=network.target
+After=network-online.target
+Wants=network-online.target
 
 [Service]
 Type=simple
-WorkingDirectory=/bin
-ExecStart=/bin/telemt /etc/telemt.toml
+User=telemt
+Group=telemt
+WorkingDirectory=/opt/telemt
+ExecStart=/bin/telemt /etc/telemt/telemt.toml
 Restart=on-failure
 LimitNOFILE=65536
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+NoNewPrivileges=true
 
 [Install]
 WantedBy=multi-user.target
 ```
 Затем нажмите Ctrl+S -> Ctrl+X, чтобы сохранить
 
+перезагрузите конфигурацию systemd
+```bash
+systemctl daemon-reload
+```
 
-**3.** Для запуска введите команду `systemctl start telemt`
+**4.** Для запуска введите команду `systemctl start telemt`
 
-**4.** Для получения информации о статусе введите `systemctl status telemt`
+**5.** Для получения информации о статусе введите `systemctl status telemt`
 
-**5.** Для автоматического запуска при запуске системы в введите `systemctl enable telemt`
+**6.** Для автоматического запуска при запуске системы в введите `systemctl enable telemt`
 
-**6.** Для получения ссылки/ссылок введите 
+**7.** Для получения ссылки/ссылок введите 
 ```bash
 curl -s http://127.0.0.1:9091/v1/users | jq
 ```
 > Одной ссылкой может пользоваться сколько угодно человек.
 
 > [!WARNING]
-> Рабочую ссылку может выдать только команда из 6 пункта. Не пытайтесь делать ее самостоятельно или копировать откуда-либо если вы не уверены в том, что делаете!
+> Рабочую ссылку может выдать только команда из 7 пункта. Не пытайтесь делать ее самостоятельно или копировать откуда-либо если вы не уверены в том, что делаете!
 
 ---
 

docs/fronting-splitting/TLS-F-TCP-S.ru.md

@@ -0,0 +1,278 @@
+# TLS-F и TCP-S в Telemt
+
+## Общая архитектура
+
+**Telemt** - это прежде всего реализация **MTProxy**, через которую проходит payload Telegram
+
+Подсистема **TLS-Fronting / TCP-Splitting** служит **маскировочным транспортным слоем**, задача которого - сделать MTProxy-соединение внешне похожим на обычное TLS-подключение к легитимному сайту
+
+Таким образом:
+
+- **MTProxy** - основной функциональный слой Telemt для обработки Telegram-трафика
+- **TLS-Fronting / TCP-Splitting** - подсистема маскировки транспорта
+
+С точки зрения сети Telemt ведёт себя как **TLS-сервер**, но фактически:
+
+- валидные MTProxy-клиенты остаются внутри контура Telemt
+- любые другие TLS-клиенты проксируются на обычный HTTPS-сервер-заглушку
+
+# Базовый сценарий / Best-practice
+
+Предположим, у вас есть домен:
+
+```
+umweltschutz.de
+```
+
+### 1 DNS
+
+Вы создаёте A-запись:
+
+```
+umweltschutz.de -> A-запись 198.18.88.88
+```
+
+где `198.18.88.88` - IP вашего сервера с telemt
+
+### 2 TLS-домен
+
+В конфигурации Telemt:
+
+```toml
+[censorship]
+tls_domain = "umweltschutz.de"
+```
+
+Этот домен используется клиентом как SNI в ClientHello
+
+### 3 Сервер-заглушка
+
+Вы поднимаете обычный HTTPS-сервер, например **nginx**, с сертификатом для этого домена.
+
+Он может работать:
+
+- на том же сервере
+- на другом сервере
+- на другом порту
+
+В конфигурации Telemt:
+
+```toml
+[censorship]
+mask_host = "127.0.0.1"
+mask_port = 8443
+```
+
+где `127.0.0.1` - IP сервера-заглушки, а 8443 - порт, который он слушает
+
+Этот сервер нужен **для обработки любых non-MTProxy запросов**
+
+### 4 Работа Telemt
+
+После запуска Telemt действует следующим образом:
+
+1) принимает входящее TCP-соединение
+2) анализирует TLS-ClientHello
+3) пытается определить, является ли соединение валидным **MTProxy FakeTLS**
+
+Далее работают два варианта логики:
+
+---
+
+# Сценарий 1 - MTProxy клиент с валидным ключом
+
+Если клиент предъявил **валидный MTProxy-ключ**:
+
+- соединение **остаётся внутри Telemt**
+- TLS используется только как **транспортная маскировка**
+- далее запускается обычная логика **MTProxy**
+
+Для внешнего наблюдателя это выглядит как:
+
+```
+TLS connection -> umweltschutz.de
+```
+
+Хотя внутри передаётся **MTProto-трафик Telegram**
+
+# Сценарий 2 - обычный TLS-клиент - crawler / scanner / browser
+
+Если Telemt не обнаруживает валидный MTProxy-ключ:
+
+соединение **переключается в режим TCP-Splitting / TCP-Splicing**.
+
+В этом режиме Telemt:
+
+1. открывает новое TCP-соединение к
+
+```
+mask_host:mask_port
+```
+
+2. начинает **проксировать TCP-трафик**
+
+Важно:
+
+* клиентский TLS-запрос **НЕ модифицируется**
+* **ClientHello передаётся "как есть", без изменений**
+* **SNI остаётся неизменным**
+* Telemt **не завершает TLS-рукопожатие**, а только перенаправляет его на более низком уровне сетевого стека - L4
+
+Таким образом upstream-сервер получает **оригинальное TLS-соединение клиента**:
+
+- если это nginx-заглушка, он просто отдаёт обычный сайт
+- для внешнего наблюдателя это выглядит как обычный HTTPS-сервер
+
+# TCP-S / TCP-Splitting / TCP-Splicing
+
+Ключевые свойства механизма:
+
+**Telemt работает как TCP-переключатель:**
+
+1) принимает соединение
+2️) определяет тип клиента
+3) либо:
+
+- обрабатывает MTProxy внутри
+- либо проксирует TCP-поток
+
+При проксировании:
+
+- Telemt **разрешает `mask_host` в IP**
+- устанавливает TCP-соединение
+- начинает **bidirectional TCP relay**
+
+При этом:
+
+- TLS-рукопожатие происходит **между клиентом и `mask_host`**
+- Telemt выступает только **на уровне L4 - как TCP-релей**, такой же как HAProxy в TCP-режиме
+
+# Использование чужого домена
+
+Можно использовать и внешний сайт.
+
+Например:
+
+```toml
+[censorship]
+tls_domain = "github.com"
+mask_host = "github.com"
+mask_port = 443
+```
+
+или
+
+```toml
+[censorship]
+mask_host = "140.82.121.4"
+```
+
+В этом случае:
+
+- цензор видит **TLS-подключение к github.com**
+- обычные клиенты/краулер действительно получают **настоящий GitHub**
+
+Telemt просто **проксирует TCP-соединение на GitHub**
+
+# Что видит анализатор трафика?
+
+Для DPI это выглядит так:
+
+```
+client -> TLS -> github.com
+```
+
+или
+
+```
+client -> TLS -> umweltschutz.de
+```
+
+TLS-handshake выглядит валидным, SNI соответствует домену, сертификат корректный - от целевого `mask_host:mask_port`
+
+# Что видит сканер / краулер?
+
+Если сканер попытается подключиться:
+
+```
+openssl s_client -connect 198.18.88.88:443 -servername umweltschutz.de
+```
+
+он получит **обычный HTTPS-сайт-заглушку**
+
+Потому что:
+
+- он не предъявил MTProxy-ключ
+- Telemt отправил соединение на `mask_host:mask_port`, на котором находится nginx 
+
+# Какую проблему решает TLS-Fronting / TCP-Splitting?
+
+Эта архитектура решает сразу несколько проблем обхода цензуры.
+
+## 1 Закрытие плоскости MTProxy от активного сканирования
+
+Многие цензоры:
+
+- сканируют IP-адреса
+- проверяют известные сигнатуры прокси
+
+Telemt отвечает на такие проверки **обычным HTTPS-сайтом**, поэтому прокси невозможно обнаружить простым сканированием
+
+---
+
+## 2 Маскировка трафика под легитимный TLS
+
+Для DPI-систем соединение выглядит как:
+
+```
+обычный TLS-трафик к популярному домену
+```
+
+Это делает блокировку значительно сложнее и непредсказуемее
+
+---
+
+## 3 Устойчивость к протокольному анализу
+
+MTProxy трафик проходит **внутри TLS-like-потока**, поэтому:
+
+- не видны характерные сигнатуры MTProto
+- соединение выглядит как обычный HTTPS
+
+---
+
+## 4 Правдоподобное поведение сервера
+
+Даже если краулер:
+
+- подключится сам
+- выполнит TLS-handshake
+- попытается получить HTTP-ответ
+
+он увидит **реальный сайт**, а не telemt
+
+Это устраняет один из главных признаков для антифрод-краулеров мобильных операторов
+
+# Схема
+
+```text
+			Client
+			  │
+			  │ TCP
+			  │
+			  V
+			Telemt
+			  │
+			  ├── valid MTProxy key
+			  │        │
+			  │        V
+			  │     MTProxy logic
+			  │
+			  └── обычный TLS клиент
+			  │
+			  V
+		 TCP-Splitting
+			  │
+			  V
+	  mask_host:mask_port
+```

install.sh

@@ -1,73 +1,115 @@
-sudo bash -c '
-set -e
+#!/bin/sh
+set -eu
 
-# --- Проверка на существующую установку ---
-if systemctl list-unit-files | grep -q telemt.service; then
-    # --- РЕЖИМ ОБНОВЛЕНИЯ ---
-    echo "--- Обнаружена существующая установка Telemt. Запускаю обновление... ---"
+REPO="${REPO:-telemt/telemt}"
+BIN_NAME="${BIN_NAME:-telemt}"
+VERSION="${1:-${VERSION:-latest}}"
+INSTALL_DIR="${INSTALL_DIR:-/usr/local/bin}"
 
-    echo "[*] Остановка службы telemt..."
-    systemctl stop telemt || true # Игнорируем ошибку, если служба уже остановлена
+say() {
+    printf '%s\n' "$*"
+}
 
-    echo "[1/2] Скачивание последней версии Telemt..."
-    wget -qO- "https://github.com/telemt/telemt/releases/latest/download/telemt-$(uname -m)-linux-$(ldd --version 2>&1 | grep -iq musl && echo musl || echo gnu).tar.gz" | tar -xz
+die() {
+    printf 'Error: %s\n' "$*" >&2
+    exit 1
+}
 
-    echo "[1/2] Замена исполняемого файла в /usr/local/bin..."
-    mv telemt /usr/local/bin/telemt
-    chmod +x /usr/local/bin/telemt
+need_cmd() {
+    command -v "$1" >/dev/null 2>&1 || die "required command not found: $1"
+}
 
-    echo "[2/2] Запуск службы..."
-    systemctl start telemt
+detect_os() {
+    os="$(uname -s)"
+    case "$os" in
+        Linux) printf 'linux\n' ;;
+        OpenBSD) printf 'openbsd\n' ;;
+        *) printf '%s\n' "$os" ;;
+    esac
+}
 
-    echo "--- Обновление Telemt успешно завершено! ---"
-    echo
-    echo "Для проверки статуса службы выполните:"
-    echo "   systemctl status telemt"
+detect_arch() {
+    arch="$(uname -m)"
+    case "$arch" in
+        x86_64|amd64) printf 'x86_64\n' ;;
+        aarch64|arm64) printf 'aarch64\n' ;;
+        *) die "unsupported architecture: $arch" ;;
+    esac
+}
 
-else
-    # --- РЕЖИМ НОВОЙ УСТАНОВКИ ---
-    echo "--- Начало автоматической установки Telemt ---"
+detect_libc() {
+    case "$(ldd --version 2>&1 || true)" in
+        *musl*) printf 'musl\n' ;;
+        *) printf 'gnu\n' ;;
+    esac
+}
 
-    # Шаг 1: Скачивание и установка бинарного файла
-    echo "[1/5] Скачивание последней версии Telemt..."
-    wget -qO- "https://github.com/telemt/telemt/releases/latest/download/telemt-$(uname -m)-linux-$(ldd --version 2>&1 | grep -iq musl && echo musl || echo gnu).tar.gz" | tar -xz
+fetch_to_stdout() {
+    url="$1"
+    if command -v curl >/dev/null 2>&1; then
+        curl -fsSL "$url"
+    elif command -v wget >/dev/null 2>&1; then
+        wget -qO- "$url"
+    else
+        die "neither curl nor wget is installed"
+    fi
+}
 
-    echo "[1/5] Перемещение исполняемого файла в /usr/local/bin и установка прав..."
-    mv telemt /usr/local/bin/telemt
-    chmod +x /usr/local/bin/telemt
+install_binary() {
+    src="$1"
+    dst="$2"
 
-    # Шаг 2: Генерация секрета
-    echo "[2/5] Генерация секретного ключа..."
-    SECRET=$(openssl rand -hex 16)
+    if [ -w "$INSTALL_DIR" ] || { [ ! -e "$INSTALL_DIR" ] && [ -w "$(dirname "$INSTALL_DIR")" ]; }; then
+        mkdir -p "$INSTALL_DIR"
+        install -m 0755 "$src" "$dst"
+    elif command -v sudo >/dev/null 2>&1; then
+        sudo mkdir -p "$INSTALL_DIR"
+        sudo install -m 0755 "$src" "$dst"
+    else
+        die "cannot write to $INSTALL_DIR and sudo is not available"
+    fi
+}
 
-    # Шаг 3: Создание файла конфигурации
-    echo "[3/5] Создание файла конфигурации /etc/telemt.toml..."
-    printf "# === General Settings ===\n[general]\n[general.modes]\nclassic = false\nsecure = false\ntls = true\n\n# === Anti-Censorship & Masking ===\n[censorship]\n# !!! ВАЖНО: Замените на ваш домен или домен, который вы хотите использовать для маскировки !!!\ntls_domain = \"petrovich.ru\"\n\n[access.users]\nhello = \"%s\"\n" "$SECRET" > /etc/telemt.toml
+need_cmd uname
+need_cmd tar
+need_cmd mktemp
+need_cmd grep
+need_cmd install
 
-    # Шаг 4: Создание службы Systemd
-    echo "[4/5] Создание службы systemd..."
-    printf "[Unit]\nDescription=Telemt Proxy\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=/usr/local/bin/telemt /etc/telemt.toml\nRestart=on-failure\nRestartSec=5\nLimitNOFILE=65536\n\n[Install]\nWantedBy=multi-user.target\n" > /etc/systemd/system/telemt.service
+ARCH="$(detect_arch)"
+OS="$(detect_os)"
 
-    # Шаг 5: Запуск службы
-    echo "[5/5] Перезагрузка systemd, запуск и включение службы telemt..."
-    systemctl daemon-reload
-    systemctl start telemt
-    systemctl enable telemt
-
-    echo "--- Установка и запуск Telemt успешно завершены! ---"
-    echo
-    echo "ВАЖНАЯ ИНФОРМАЦИЯ:"
-    echo "==================="
-    echo "1. Вам НЕОБХОДИМО отредактировать файл /etc/telemt.toml и заменить '\''petrovich.ru'\'' на другой домен"
-    echo "   с помощью команды:"
-    echo "   nano /etc/telemt.toml"
-    echo "   После редактирования файла перезапустите службу командой:"
-    echo "   sudo systemctl restart telemt"
-    echo
-    echo "2. Для проверки статуса службы выполните команду:"
-    echo "   systemctl status telemt"
-    echo
-    echo "3. Для получения ссылок на подключение выполните команду:"
-    echo "   journalctl -u telemt -n -g '\''links'\'' --no-pager -o cat | tac"
+if [ "$OS" != "linux" ]; then
+    case "$OS" in
+        openbsd)
+            die "install.sh installs only Linux release artifacts. On OpenBSD, build from source (see docs/OPENBSD.en.md)."
+            ;;
+        *)
+            die "unsupported operating system for install.sh: $OS"
+            ;;
+    esac
 fi
-'
+
+LIBC="$(detect_libc)"
+
+case "$VERSION" in
+    latest)
+        URL="https://github.com/$REPO/releases/latest/download/${BIN_NAME}-${ARCH}-linux-${LIBC}.tar.gz"
+        ;;
+    *)
+        URL="https://github.com/$REPO/releases/download/${VERSION}/${BIN_NAME}-${ARCH}-linux-${LIBC}.tar.gz"
+        ;;
+esac
+
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT INT TERM
+
+say "Installing $BIN_NAME ($VERSION) for $ARCH-linux-$LIBC..."
+fetch_to_stdout "$URL" | tar -xzf - -C "$TMPDIR"
+
+[ -f "$TMPDIR/$BIN_NAME" ] || die "archive did not contain $BIN_NAME"
+
+install_binary "$TMPDIR/$BIN_NAME" "$INSTALL_DIR/$BIN_NAME"
+
+say "Installed: $INSTALL_DIR/$BIN_NAME"
+"$INSTALL_DIR/$BIN_NAME" --version 2>/dev/null || true

src/api/config_store.rs

@@ -1,13 +1,39 @@
+use std::collections::BTreeMap;
 use std::io::Write;
 use std::path::{Path, PathBuf};
 
+use chrono::{DateTime, Utc};
 use hyper::header::IF_MATCH;
+use serde::Serialize;
 use sha2::{Digest, Sha256};
 
 use crate::config::ProxyConfig;
 
 use super::model::ApiFailure;
 
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(super) enum AccessSection {
+    Users,
+    UserAdTags,
+    UserMaxTcpConns,
+    UserExpirations,
+    UserDataQuota,
+    UserMaxUniqueIps,
+}
+
+impl AccessSection {
+    fn table_name(self) -> &'static str {
+        match self {
+            Self::Users => "access.users",
+            Self::UserAdTags => "access.user_ad_tags",
+            Self::UserMaxTcpConns => "access.user_max_tcp_conns",
+            Self::UserExpirations => "access.user_expirations",
+            Self::UserDataQuota => "access.user_data_quota",
+            Self::UserMaxUniqueIps => "access.user_max_unique_ips",
+        }
+    }
+}
+
 pub(super) fn parse_if_match(headers: &hyper::HeaderMap) -> Option<String> {
     headers
         .get(IF_MATCH)
@@ -66,6 +92,142 @@ pub(super) async fn save_config_to_disk(
     Ok(compute_revision(&serialized))
 }
 
+pub(super) async fn save_access_sections_to_disk(
+    config_path: &Path,
+    cfg: &ProxyConfig,
+    sections: &[AccessSection],
+) -> Result<String, ApiFailure> {
+    let mut content = tokio::fs::read_to_string(config_path)
+        .await
+        .map_err(|e| ApiFailure::internal(format!("failed to read config: {}", e)))?;
+
+    let mut applied = Vec::new();
+    for section in sections {
+        if applied.contains(section) {
+            continue;
+        }
+        let rendered = render_access_section(cfg, *section)?;
+        content = upsert_toml_table(&content, section.table_name(), &rendered);
+        applied.push(*section);
+    }
+
+    write_atomic(config_path.to_path_buf(), content.clone()).await?;
+    Ok(compute_revision(&content))
+}
+
+fn render_access_section(cfg: &ProxyConfig, section: AccessSection) -> Result<String, ApiFailure> {
+    let body = match section {
+        AccessSection::Users => {
+            let rows: BTreeMap<String, String> = cfg
+                .access
+                .users
+                .iter()
+                .map(|(key, value)| (key.clone(), value.clone()))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserAdTags => {
+            let rows: BTreeMap<String, String> = cfg
+                .access
+                .user_ad_tags
+                .iter()
+                .map(|(key, value)| (key.clone(), value.clone()))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserMaxTcpConns => {
+            let rows: BTreeMap<String, usize> = cfg
+                .access
+                .user_max_tcp_conns
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserExpirations => {
+            let rows: BTreeMap<String, DateTime<Utc>> = cfg
+                .access
+                .user_expirations
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserDataQuota => {
+            let rows: BTreeMap<String, u64> = cfg
+                .access
+                .user_data_quota
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserMaxUniqueIps => {
+            let rows: BTreeMap<String, usize> = cfg
+                .access
+                .user_max_unique_ips
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+    };
+
+    let mut out = format!("[{}]\n", section.table_name());
+    if !body.is_empty() {
+        out.push_str(&body);
+    }
+    if !out.ends_with('\n') {
+        out.push('\n');
+    }
+    Ok(out)
+}
+
+fn serialize_table_body<T: Serialize>(value: &T) -> Result<String, ApiFailure> {
+    toml::to_string(value)
+        .map_err(|e| ApiFailure::internal(format!("failed to serialize access section: {}", e)))
+}
+
+fn upsert_toml_table(source: &str, table_name: &str, replacement: &str) -> String {
+    if let Some((start, end)) = find_toml_table_bounds(source, table_name) {
+        let mut out = String::with_capacity(source.len() + replacement.len());
+        out.push_str(&source[..start]);
+        out.push_str(replacement);
+        out.push_str(&source[end..]);
+        return out;
+    }
+
+    let mut out = source.to_string();
+    if !out.is_empty() && !out.ends_with('\n') {
+        out.push('\n');
+    }
+    if !out.is_empty() {
+        out.push('\n');
+    }
+    out.push_str(replacement);
+    out
+}
+
+fn find_toml_table_bounds(source: &str, table_name: &str) -> Option<(usize, usize)> {
+    let target = format!("[{}]", table_name);
+    let mut offset = 0usize;
+    let mut start = None;
+
+    for line in source.split_inclusive('\n') {
+        let trimmed = line.trim();
+        if let Some(start_offset) = start {
+            if trimmed.starts_with('[') {
+                return Some((start_offset, offset));
+            }
+        } else if trimmed == target {
+            start = Some(offset);
+        }
+        offset = offset.saturating_add(line.len());
+    }
+
+    start.map(|start_offset| (start_offset, source.len()))
+}
+
 async fn write_atomic(path: PathBuf, contents: String) -> Result<(), ApiFailure> {
     tokio::task::spawn_blocking(move || write_atomic_sync(&path, &contents))
         .await

src/api/mod.rs

@@ -16,6 +16,7 @@ use tracing::{debug, info, warn};
 
 use crate::config::ProxyConfig;
 use crate::ip_tracker::UserIpTracker;
+use crate::proxy::route_mode::RouteRuntimeController;
 use crate::startup::StartupTracker;
 use crate::stats::Stats;
 use crate::transport::middle_proxy::MePool;
@@ -28,6 +29,7 @@ mod model;
 mod runtime_edge;
 mod runtime_init;
 mod runtime_min;
+mod runtime_selftest;
 mod runtime_stats;
 mod runtime_watch;
 mod runtime_zero;
@@ -48,6 +50,7 @@ use runtime_min::{
     build_runtime_me_pool_state_data, build_runtime_me_quality_data, build_runtime_nat_stun_data,
     build_runtime_upstream_quality_data, build_security_whitelist_data,
 };
+use runtime_selftest::build_runtime_me_selftest_data;
 use runtime_stats::{
     MinimalCacheEntry, build_dcs_data, build_me_writers_data, build_minimal_all_data,
     build_upstreams_data, build_zero_all_data,
@@ -73,8 +76,7 @@ pub(super) struct ApiShared {
     pub(super) me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
     pub(super) upstream_manager: Arc<UpstreamManager>,
     pub(super) config_path: PathBuf,
-    pub(super) startup_detected_ip_v4: Option<IpAddr>,
-    pub(super) startup_detected_ip_v6: Option<IpAddr>,
+    pub(super) detected_ips_rx: watch::Receiver<(Option<IpAddr>, Option<IpAddr>)>,
     pub(super) mutation_lock: Arc<Mutex<()>>,
     pub(super) minimal_cache: Arc<Mutex<Option<MinimalCacheEntry>>>,
     pub(super) runtime_edge_connections_cache: Arc<Mutex<Option<EdgeConnectionsCacheEntry>>>,
@@ -83,12 +85,17 @@ pub(super) struct ApiShared {
     pub(super) request_id: Arc<AtomicU64>,
     pub(super) runtime_state: Arc<ApiRuntimeState>,
     pub(super) startup_tracker: Arc<StartupTracker>,
+    pub(super) route_runtime: Arc<RouteRuntimeController>,
 }
 
 impl ApiShared {
     fn next_request_id(&self) -> u64 {
         self.request_id.fetch_add(1, Ordering::Relaxed)
     }
+
+    fn detected_link_ips(&self) -> (Option<IpAddr>, Option<IpAddr>) {
+        *self.detected_ips_rx.borrow()
+    }
 }
 
 pub async fn serve(
@@ -96,12 +103,12 @@ pub async fn serve(
     stats: Arc<Stats>,
     ip_tracker: Arc<UserIpTracker>,
     me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
+    route_runtime: Arc<RouteRuntimeController>,
     upstream_manager: Arc<UpstreamManager>,
     config_rx: watch::Receiver<Arc<ProxyConfig>>,
     admission_rx: watch::Receiver<bool>,
     config_path: PathBuf,
-    startup_detected_ip_v4: Option<IpAddr>,
-    startup_detected_ip_v6: Option<IpAddr>,
+    detected_ips_rx: watch::Receiver<(Option<IpAddr>, Option<IpAddr>)>,
     process_started_at_epoch_secs: u64,
     startup_tracker: Arc<StartupTracker>,
 ) {
@@ -132,8 +139,7 @@ pub async fn serve(
         me_pool,
         upstream_manager,
         config_path,
-        startup_detected_ip_v4,
-        startup_detected_ip_v6,
+        detected_ips_rx,
         mutation_lock: Arc::new(Mutex::new(())),
         minimal_cache: Arc::new(Mutex::new(None)),
         runtime_edge_connections_cache: Arc::new(Mutex::new(None)),
@@ -144,6 +150,7 @@ pub async fn serve(
         request_id: Arc::new(AtomicU64::new(1)),
         runtime_state: runtime_state.clone(),
         startup_tracker,
+        route_runtime,
     });
 
     spawn_runtime_watchers(
@@ -333,6 +340,11 @@ async fn handle(
                 let data = build_runtime_nat_stun_data(shared.as_ref()).await;
                 Ok(success_response(StatusCode::OK, data, revision))
             }
+            ("GET", "/v1/runtime/me-selftest") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_runtime_me_selftest_data(shared.as_ref(), cfg.as_ref()).await;
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
             ("GET", "/v1/runtime/connections/summary") => {
                 let revision = current_revision(&shared.config_path).await?;
                 let data = build_runtime_connections_summary_data(shared.as_ref(), cfg.as_ref()).await;
@@ -349,12 +361,13 @@ async fn handle(
             }
             ("GET", "/v1/stats/users") | ("GET", "/v1/users") => {
                 let revision = current_revision(&shared.config_path).await?;
+                let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
                 let users = users_from_config(
                     &cfg,
                     &shared.stats,
                     &shared.ip_tracker,
-                    shared.startup_detected_ip_v4,
-                    shared.startup_detected_ip_v6,
+                    detected_ip_v4,
+                    detected_ip_v6,
                 )
                 .await;
                 Ok(success_response(StatusCode::OK, users, revision))
@@ -392,12 +405,13 @@ async fn handle(
                 {
                     if method == Method::GET {
                         let revision = current_revision(&shared.config_path).await?;
+                        let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
                         let users = users_from_config(
                             &cfg,
                             &shared.stats,
                             &shared.ip_tracker,
-                            shared.startup_detected_ip_v4,
-                            shared.startup_detected_ip_v6,
+                            detected_ip_v4,
+                            detected_ip_v6,
                         )
                         .await;
                         if let Some(user_info) = users.into_iter().find(|entry| entry.username == user)

src/api/model.rs

@@ -236,6 +236,8 @@ pub(super) struct MeWritersSummary {
     pub(super) required_writers: usize,
     pub(super) alive_writers: usize,
     pub(super) coverage_pct: f64,
+    pub(super) fresh_alive_writers: usize,
+    pub(super) fresh_coverage_pct: f64,
 }
 
 #[derive(Serialize, Clone)]
@@ -250,6 +252,12 @@ pub(super) struct MeWriterStatus {
     pub(super) bound_clients: usize,
     pub(super) idle_for_secs: Option<u64>,
     pub(super) rtt_ema_ms: Option<f64>,
+    pub(super) matches_active_generation: bool,
+    pub(super) in_desired_map: bool,
+    pub(super) allow_drain_fallback: bool,
+    pub(super) drain_started_at_epoch_secs: Option<u64>,
+    pub(super) drain_deadline_epoch_secs: Option<u64>,
+    pub(super) drain_over_ttl: bool,
 }
 
 #[derive(Serialize, Clone)]
@@ -266,6 +274,7 @@ pub(super) struct MeWritersData {
 pub(super) struct DcStatus {
     pub(super) dc: i16,
     pub(super) endpoints: Vec<String>,
+    pub(super) endpoint_writers: Vec<DcEndpointWriters>,
     pub(super) available_endpoints: usize,
     pub(super) available_pct: f64,
     pub(super) required_writers: usize,
@@ -275,10 +284,18 @@ pub(super) struct DcStatus {
     pub(super) floor_capped: bool,
     pub(super) alive_writers: usize,
     pub(super) coverage_pct: f64,
+    pub(super) fresh_alive_writers: usize,
+    pub(super) fresh_coverage_pct: f64,
     pub(super) rtt_ms: Option<f64>,
     pub(super) load: usize,
 }
 
+#[derive(Serialize, Clone)]
+pub(super) struct DcEndpointWriters {
+    pub(super) endpoint: String,
+    pub(super) active_writers: usize,
+}
+
 #[derive(Serialize, Clone)]
 pub(super) struct DcStatusData {
     pub(super) middle_proxy_enabled: bool,
@@ -354,6 +371,8 @@ pub(super) struct MinimalMeRuntimeData {
     pub(super) me_single_endpoint_outage_backoff_max_ms: u64,
     pub(super) me_single_endpoint_shadow_rotate_every_secs: u64,
     pub(super) me_deterministic_writer_sort: bool,
+    pub(super) me_writer_pick_mode: &'static str,
+    pub(super) me_writer_pick_sample_size: u8,
     pub(super) me_socks_kdf_policy: &'static str,
     pub(super) quarantined_endpoints_total: usize,
     pub(super) quarantined_endpoints: Vec<MinimalQuarantineData>,

src/api/runtime_selftest.rs

@@ -0,0 +1,299 @@
+use std::net::IpAddr;
+use std::collections::HashMap;
+use std::sync::{Mutex, OnceLock};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde::Serialize;
+
+use crate::config::{ProxyConfig, UpstreamType};
+use crate::network::probe::{detect_interface_ipv4, detect_interface_ipv6, is_bogon};
+use crate::transport::middle_proxy::{bnd_snapshot, timeskew_snapshot, upstream_bnd_snapshots};
+use crate::transport::UpstreamRouteKind;
+
+use super::ApiShared;
+
+const SOURCE_UNAVAILABLE_REASON: &str = "source_unavailable";
+const KDF_EWMA_TAU_SECS: f64 = 600.0;
+const KDF_EWMA_THRESHOLD_ERRORS_PER_MIN: f64 = 0.30;
+const TIMESKEW_THRESHOLD_SECS: u64 = 60;
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestKdfData {
+    pub(super) state: &'static str,
+    pub(super) ewma_errors_per_min: f64,
+    pub(super) threshold_errors_per_min: f64,
+    pub(super) errors_total: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestTimeskewData {
+    pub(super) state: &'static str,
+    pub(super) max_skew_secs_15m: Option<u64>,
+    pub(super) samples_15m: usize,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) last_skew_secs: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) last_source: Option<&'static str>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) last_seen_age_secs: Option<u64>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestIpFamilyData {
+    pub(super) addr: String,
+    pub(super) state: &'static str,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestIpData {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) v4: Option<RuntimeMeSelftestIpFamilyData>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) v6: Option<RuntimeMeSelftestIpFamilyData>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestPidData {
+    pub(super) pid: u32,
+    pub(super) state: &'static str,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestBndData {
+    pub(super) addr_state: &'static str,
+    pub(super) port_state: &'static str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) last_addr: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) last_seen_age_secs: Option<u64>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestUpstreamData {
+    pub(super) upstream_id: usize,
+    pub(super) route_kind: &'static str,
+    pub(super) address: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) bnd: Option<RuntimeMeSelftestBndData>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) ip: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestPayload {
+    pub(super) kdf: RuntimeMeSelftestKdfData,
+    pub(super) timeskew: RuntimeMeSelftestTimeskewData,
+    pub(super) ip: RuntimeMeSelftestIpData,
+    pub(super) pid: RuntimeMeSelftestPidData,
+    pub(super) bnd: Option<RuntimeMeSelftestBndData>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) upstreams: Option<Vec<RuntimeMeSelftestUpstreamData>>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestData {
+    pub(super) enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) data: Option<RuntimeMeSelftestPayload>,
+}
+
+#[derive(Default)]
+struct KdfEwmaState {
+    initialized: bool,
+    last_epoch_secs: u64,
+    last_total_errors: u64,
+    ewma_errors_per_min: f64,
+}
+
+static KDF_EWMA_STATE: OnceLock<Mutex<KdfEwmaState>> = OnceLock::new();
+
+fn kdf_ewma_state() -> &'static Mutex<KdfEwmaState> {
+    KDF_EWMA_STATE.get_or_init(|| Mutex::new(KdfEwmaState::default()))
+}
+
+pub(super) async fn build_runtime_me_selftest_data(
+    shared: &ApiShared,
+    cfg: &ProxyConfig,
+) -> RuntimeMeSelftestData {
+    let now_epoch_secs = now_epoch_secs();
+    if shared.me_pool.read().await.is_none() {
+        return RuntimeMeSelftestData {
+            enabled: false,
+            reason: Some(SOURCE_UNAVAILABLE_REASON),
+            generated_at_epoch_secs: now_epoch_secs,
+            data: None,
+        };
+    }
+
+    let kdf_errors_total = shared
+        .stats
+        .get_me_kdf_drift_total()
+        .saturating_add(shared.stats.get_me_socks_kdf_strict_reject());
+    let kdf_ewma = update_kdf_ewma(now_epoch_secs, kdf_errors_total);
+    let kdf_state = if kdf_ewma >= KDF_EWMA_THRESHOLD_ERRORS_PER_MIN {
+        "error"
+    } else {
+        "ok"
+    };
+
+    let skew = timeskew_snapshot();
+    let timeskew_state = if skew.max_skew_secs_15m.unwrap_or(0) > TIMESKEW_THRESHOLD_SECS {
+        "error"
+    } else {
+        "ok"
+    };
+
+    let ip_v4 = detect_interface_ipv4().map(|ip| RuntimeMeSelftestIpFamilyData {
+        addr: ip.to_string(),
+        state: classify_ip(IpAddr::V4(ip)),
+    });
+    let ip_v6 = detect_interface_ipv6().map(|ip| RuntimeMeSelftestIpFamilyData {
+        addr: ip.to_string(),
+        state: classify_ip(IpAddr::V6(ip)),
+    });
+
+    let pid = std::process::id();
+    let pid_state = if pid == 1 { "one" } else { "non-one" };
+
+    let has_socks_upstreams = cfg.upstreams.iter().any(|upstream| {
+        upstream.enabled
+            && matches!(
+                upstream.upstream_type,
+                UpstreamType::Socks4 { .. } | UpstreamType::Socks5 { .. }
+            )
+    });
+
+    let bnd = if has_socks_upstreams {
+        let snapshot = bnd_snapshot();
+        Some(RuntimeMeSelftestBndData {
+            addr_state: snapshot.addr_status,
+            port_state: snapshot.port_status,
+            last_addr: snapshot.last_addr.map(|value| value.to_string()),
+            last_seen_age_secs: snapshot.last_seen_age_secs,
+        })
+    } else {
+        None
+    };
+    let upstreams = build_upstream_selftest_data(shared);
+
+    RuntimeMeSelftestData {
+        enabled: true,
+        reason: None,
+        generated_at_epoch_secs: now_epoch_secs,
+        data: Some(RuntimeMeSelftestPayload {
+            kdf: RuntimeMeSelftestKdfData {
+                state: kdf_state,
+                ewma_errors_per_min: round3(kdf_ewma),
+                threshold_errors_per_min: KDF_EWMA_THRESHOLD_ERRORS_PER_MIN,
+                errors_total: kdf_errors_total,
+            },
+            timeskew: RuntimeMeSelftestTimeskewData {
+                state: timeskew_state,
+                max_skew_secs_15m: skew.max_skew_secs_15m,
+                samples_15m: skew.samples_15m,
+                last_skew_secs: skew.last_skew_secs,
+                last_source: skew.last_source,
+                last_seen_age_secs: skew.last_seen_age_secs,
+            },
+            ip: RuntimeMeSelftestIpData {
+                v4: ip_v4,
+                v6: ip_v6,
+            },
+            pid: RuntimeMeSelftestPidData {
+                pid,
+                state: pid_state,
+            },
+            bnd,
+            upstreams,
+        }),
+    }
+}
+
+fn build_upstream_selftest_data(shared: &ApiShared) -> Option<Vec<RuntimeMeSelftestUpstreamData>> {
+    let snapshot = shared.upstream_manager.try_api_snapshot()?;
+    if snapshot.summary.configured_total <= 1 {
+        return None;
+    }
+
+    let mut upstream_bnd_by_id: HashMap<usize, _> = upstream_bnd_snapshots()
+        .into_iter()
+        .map(|entry| (entry.upstream_id, entry))
+        .collect();
+    let mut rows = Vec::with_capacity(snapshot.upstreams.len());
+    for upstream in snapshot.upstreams {
+        let upstream_bnd = upstream_bnd_by_id.remove(&upstream.upstream_id);
+        rows.push(RuntimeMeSelftestUpstreamData {
+            upstream_id: upstream.upstream_id,
+            route_kind: map_route_kind(upstream.route_kind),
+            address: upstream.address,
+            bnd: upstream_bnd.as_ref().map(|entry| RuntimeMeSelftestBndData {
+                addr_state: entry.addr_status,
+                port_state: entry.port_status,
+                last_addr: entry.last_addr.map(|value| value.to_string()),
+                last_seen_age_secs: entry.last_seen_age_secs,
+            }),
+            ip: upstream_bnd.and_then(|entry| entry.last_ip.map(|value| value.to_string())),
+        });
+    }
+    Some(rows)
+}
+
+fn update_kdf_ewma(now_epoch_secs: u64, total_errors: u64) -> f64 {
+    let Ok(mut guard) = kdf_ewma_state().lock() else {
+        return 0.0;
+    };
+
+    if !guard.initialized {
+        guard.initialized = true;
+        guard.last_epoch_secs = now_epoch_secs;
+        guard.last_total_errors = total_errors;
+        guard.ewma_errors_per_min = 0.0;
+        return guard.ewma_errors_per_min;
+    }
+
+    let dt_secs = now_epoch_secs.saturating_sub(guard.last_epoch_secs);
+    if dt_secs == 0 {
+        return guard.ewma_errors_per_min;
+    }
+
+    let delta_errors = total_errors.saturating_sub(guard.last_total_errors);
+    let instant_rate_per_min = (delta_errors as f64) * 60.0 / (dt_secs as f64);
+    let alpha = 1.0 - f64::exp(-(dt_secs as f64) / KDF_EWMA_TAU_SECS);
+    guard.ewma_errors_per_min = guard.ewma_errors_per_min
+        + alpha * (instant_rate_per_min - guard.ewma_errors_per_min);
+    guard.last_epoch_secs = now_epoch_secs;
+    guard.last_total_errors = total_errors;
+    guard.ewma_errors_per_min
+}
+
+fn classify_ip(ip: IpAddr) -> &'static str {
+    if ip.is_loopback() {
+        return "loopback";
+    }
+    if is_bogon(ip) {
+        return "bogon";
+    }
+    "good"
+}
+
+fn map_route_kind(value: UpstreamRouteKind) -> &'static str {
+    match value {
+        UpstreamRouteKind::Direct => "direct",
+        UpstreamRouteKind::Socks4 => "socks4",
+        UpstreamRouteKind::Socks5 => "socks5",
+    }
+}
+
+fn round3(value: f64) -> f64 {
+    (value * 1000.0).round() / 1000.0
+}
+
+fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}

src/api/runtime_stats.rs

@@ -7,10 +7,10 @@ use crate::transport::UpstreamRouteKind;
 
 use super::ApiShared;
 use super::model::{
-    DcStatus, DcStatusData, MeWriterStatus, MeWritersData, MeWritersSummary, MinimalAllData,
-    MinimalAllPayload, MinimalDcPathData, MinimalMeRuntimeData, MinimalQuarantineData,
-    UpstreamDcStatus, UpstreamStatus, UpstreamSummaryData, UpstreamsData, ZeroAllData,
-    ZeroCodeCount, ZeroCoreData, ZeroDesyncData, ZeroMiddleProxyData, ZeroPoolData,
+    DcEndpointWriters, DcStatus, DcStatusData, MeWriterStatus, MeWritersData, MeWritersSummary,
+    MinimalAllData, MinimalAllPayload, MinimalDcPathData, MinimalMeRuntimeData,
+    MinimalQuarantineData, UpstreamDcStatus, UpstreamStatus, UpstreamSummaryData, UpstreamsData,
+    ZeroAllData, ZeroCodeCount, ZeroCoreData, ZeroDesyncData, ZeroMiddleProxyData, ZeroPoolData,
     ZeroUpstreamData,
 };
 
@@ -314,6 +314,8 @@ async fn get_minimal_payload_cached(
             required_writers: status.required_writers,
             alive_writers: status.alive_writers,
             coverage_pct: status.coverage_pct,
+            fresh_alive_writers: status.fresh_alive_writers,
+            fresh_coverage_pct: status.fresh_coverage_pct,
         },
         writers: status
             .writers
@@ -329,6 +331,12 @@ async fn get_minimal_payload_cached(
                 bound_clients: entry.bound_clients,
                 idle_for_secs: entry.idle_for_secs,
                 rtt_ema_ms: entry.rtt_ema_ms,
+                matches_active_generation: entry.matches_active_generation,
+                in_desired_map: entry.in_desired_map,
+                allow_drain_fallback: entry.allow_drain_fallback,
+                drain_started_at_epoch_secs: entry.drain_started_at_epoch_secs,
+                drain_deadline_epoch_secs: entry.drain_deadline_epoch_secs,
+                drain_over_ttl: entry.drain_over_ttl,
             })
             .collect(),
     };
@@ -346,6 +354,14 @@ async fn get_minimal_payload_cached(
                     .into_iter()
                     .map(|value| value.to_string())
                     .collect(),
+                endpoint_writers: entry
+                    .endpoint_writers
+                    .into_iter()
+                    .map(|coverage| DcEndpointWriters {
+                        endpoint: coverage.endpoint.to_string(),
+                        active_writers: coverage.active_writers,
+                    })
+                    .collect(),
                 available_endpoints: entry.available_endpoints,
                 available_pct: entry.available_pct,
                 required_writers: entry.required_writers,
@@ -355,6 +371,8 @@ async fn get_minimal_payload_cached(
                 floor_capped: entry.floor_capped,
                 alive_writers: entry.alive_writers,
                 coverage_pct: entry.coverage_pct,
+                fresh_alive_writers: entry.fresh_alive_writers,
+                fresh_coverage_pct: entry.fresh_coverage_pct,
                 rtt_ms: entry.rtt_ms,
                 load: entry.load,
             })
@@ -422,6 +440,8 @@ async fn get_minimal_payload_cached(
         me_single_endpoint_shadow_rotate_every_secs: runtime
             .me_single_endpoint_shadow_rotate_every_secs,
         me_deterministic_writer_sort: runtime.me_deterministic_writer_sort,
+        me_writer_pick_mode: runtime.me_writer_pick_mode,
+        me_writer_pick_sample_size: runtime.me_writer_pick_sample_size,
         me_socks_kdf_policy: runtime.me_socks_kdf_policy,
         quarantined_endpoints_total: runtime.quarantined_endpoints.len(),
         quarantined_endpoints: runtime
@@ -476,6 +496,8 @@ fn disabled_me_writers(now_epoch_secs: u64, reason: &'static str) -> MeWritersDa
             required_writers: 0,
             alive_writers: 0,
             coverage_pct: 0.0,
+            fresh_alive_writers: 0,
+            fresh_coverage_pct: 0.0,
         },
         writers: Vec::new(),
     }

src/api/runtime_zero.rs

@@ -2,7 +2,8 @@ use std::sync::atomic::Ordering;
 
 use serde::Serialize;
 
-use crate::config::{MeFloorMode, ProxyConfig, UserMaxUniqueIpsMode};
+use crate::config::{MeFloorMode, MeWriterPickMode, ProxyConfig, UserMaxUniqueIpsMode};
+use crate::proxy::route_mode::RelayRouteMode;
 
 use super::ApiShared;
 use super::runtime_init::build_runtime_startup_summary;
@@ -35,6 +36,10 @@ pub(super) struct RuntimeGatesData {
     pub(super) me_runtime_ready: bool,
     pub(super) me2dc_fallback_enabled: bool,
     pub(super) use_middle_proxy: bool,
+    pub(super) route_mode: &'static str,
+    pub(super) reroute_active: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reroute_to_direct_at_epoch_secs: Option<u64>,
     pub(super) startup_status: &'static str,
     pub(super) startup_stage: String,
     pub(super) startup_progress_pct: f64,
@@ -78,11 +83,14 @@ pub(super) struct EffectiveMiddleProxyLimits {
     pub(super) reconnect_backoff_base_ms: u64,
     pub(super) reconnect_backoff_cap_ms: u64,
     pub(super) reconnect_fast_retry_count: u32,
+    pub(super) writer_pick_mode: &'static str,
+    pub(super) writer_pick_sample_size: u8,
     pub(super) me2dc_fallback: bool,
 }
 
 #[derive(Serialize)]
 pub(super) struct EffectiveUserIpPolicyLimits {
+    pub(super) global_each: usize,
     pub(super) mode: &'static str,
     pub(super) window_secs: u64,
 }
@@ -155,6 +163,16 @@ pub(super) async fn build_runtime_gates_data(
     cfg: &ProxyConfig,
 ) -> RuntimeGatesData {
     let startup_summary = build_runtime_startup_summary(shared).await;
+    let route_state = shared.route_runtime.snapshot();
+    let route_mode = route_state.mode.as_str();
+    let reroute_active = cfg.general.use_middle_proxy
+        && cfg.general.me2dc_fallback
+        && matches!(route_state.mode, RelayRouteMode::Direct);
+    let reroute_to_direct_at_epoch_secs = if reroute_active {
+        shared.route_runtime.direct_since_epoch_secs()
+    } else {
+        None
+    };
     let me_runtime_ready = if !cfg.general.use_middle_proxy {
         true
     } else {
@@ -173,6 +191,9 @@ pub(super) async fn build_runtime_gates_data(
         me_runtime_ready,
         me2dc_fallback_enabled: cfg.general.me2dc_fallback,
         use_middle_proxy: cfg.general.use_middle_proxy,
+        route_mode,
+        reroute_active,
+        reroute_to_direct_at_epoch_secs,
         startup_status: startup_summary.status,
         startup_stage: startup_summary.stage,
         startup_progress_pct: startup_summary.progress_pct,
@@ -237,9 +258,12 @@ pub(super) fn build_limits_effective_data(cfg: &ProxyConfig) -> EffectiveLimitsD
             reconnect_backoff_base_ms: cfg.general.me_reconnect_backoff_base_ms,
             reconnect_backoff_cap_ms: cfg.general.me_reconnect_backoff_cap_ms,
             reconnect_fast_retry_count: cfg.general.me_reconnect_fast_retry_count,
+            writer_pick_mode: me_writer_pick_mode_label(cfg.general.me_writer_pick_mode),
+            writer_pick_sample_size: cfg.general.me_writer_pick_sample_size,
             me2dc_fallback: cfg.general.me2dc_fallback,
         },
         user_ip_policy: EffectiveUserIpPolicyLimits {
+            global_each: cfg.access.user_max_unique_ips_global_each,
             mode: user_max_unique_ips_mode_label(cfg.access.user_max_unique_ips_mode),
             window_secs: cfg.access.user_max_unique_ips_window_secs,
         },
@@ -274,3 +298,10 @@ fn me_floor_mode_label(mode: MeFloorMode) -> &'static str {
         MeFloorMode::Adaptive => "adaptive",
     }
 }
+
+fn me_writer_pick_mode_label(mode: MeWriterPickMode) -> &'static str {
+    match mode {
+        MeWriterPickMode::SortedRr => "sorted_rr",
+        MeWriterPickMode::P2c => "p2c",
+    }
+}

src/api/users.rs

@@ -8,7 +8,8 @@ use crate::stats::Stats;
 
 use super::ApiShared;
 use super::config_store::{
-    ensure_expected_revision, load_config_from_disk, save_config_to_disk,
+    AccessSection, ensure_expected_revision, load_config_from_disk, save_access_sections_to_disk,
+    save_config_to_disk,
 };
 use super::model::{
     ApiFailure, CreateUserRequest, CreateUserResponse, PatchUserRequest, RotateSecretRequest,
@@ -21,6 +22,12 @@ pub(super) async fn create_user(
     expected_revision: Option<String>,
     shared: &ApiShared,
 ) -> Result<(CreateUserResponse, String), ApiFailure> {
+    let touches_user_ad_tags = body.user_ad_tag.is_some();
+    let touches_user_max_tcp_conns = body.max_tcp_conns.is_some();
+    let touches_user_expirations = body.expiration_rfc3339.is_some();
+    let touches_user_data_quota = body.data_quota_bytes.is_some();
+    let touches_user_max_unique_ips = body.max_unique_ips.is_some();
+
     if !is_valid_username(&body.username) {
         return Err(ApiFailure::bad_request(
             "username must match [A-Za-z0-9_.-] and be 1..64 chars",
@@ -84,19 +91,37 @@ pub(super) async fn create_user(
     cfg.validate()
         .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
 
-    let revision = save_config_to_disk(&shared.config_path, &cfg).await?;
+    let mut touched_sections = vec![AccessSection::Users];
+    if touches_user_ad_tags {
+        touched_sections.push(AccessSection::UserAdTags);
+    }
+    if touches_user_max_tcp_conns {
+        touched_sections.push(AccessSection::UserMaxTcpConns);
+    }
+    if touches_user_expirations {
+        touched_sections.push(AccessSection::UserExpirations);
+    }
+    if touches_user_data_quota {
+        touched_sections.push(AccessSection::UserDataQuota);
+    }
+    if touches_user_max_unique_ips {
+        touched_sections.push(AccessSection::UserMaxUniqueIps);
+    }
+
+    let revision = save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
     drop(_guard);
 
     if let Some(limit) = updated_limit {
         shared.ip_tracker.set_user_limit(&body.username, limit).await;
     }
+    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
 
     let users = users_from_config(
         &cfg,
         &shared.stats,
         &shared.ip_tracker,
-        shared.startup_detected_ip_v4,
-        shared.startup_detected_ip_v6,
+        detected_ip_v4,
+        detected_ip_v6,
     )
     .await;
     let user = users
@@ -118,8 +143,8 @@ pub(super) async fn create_user(
             links: build_user_links(
                 &cfg,
                 &secret,
-                shared.startup_detected_ip_v4,
-                shared.startup_detected_ip_v6,
+                detected_ip_v4,
+                detected_ip_v6,
             ),
         });
 
@@ -185,12 +210,13 @@ pub(super) async fn patch_user(
     if let Some(limit) = updated_limit {
         shared.ip_tracker.set_user_limit(user, limit).await;
     }
+    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
     let users = users_from_config(
         &cfg,
         &shared.stats,
         &shared.ip_tracker,
-        shared.startup_detected_ip_v4,
-        shared.startup_detected_ip_v6,
+        detected_ip_v4,
+        detected_ip_v6,
     )
     .await;
     let user_info = users
@@ -229,15 +255,24 @@ pub(super) async fn rotate_secret(
     cfg.access.users.insert(user.to_string(), secret.clone());
     cfg.validate()
         .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
-    let revision = save_config_to_disk(&shared.config_path, &cfg).await?;
+    let touched_sections = [
+        AccessSection::Users,
+        AccessSection::UserAdTags,
+        AccessSection::UserMaxTcpConns,
+        AccessSection::UserExpirations,
+        AccessSection::UserDataQuota,
+        AccessSection::UserMaxUniqueIps,
+    ];
+    let revision = save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
     drop(_guard);
 
+    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
     let users = users_from_config(
         &cfg,
         &shared.stats,
         &shared.ip_tracker,
-        shared.startup_detected_ip_v4,
-        shared.startup_detected_ip_v6,
+        detected_ip_v4,
+        detected_ip_v6,
     )
     .await;
     let user_info = users
@@ -287,7 +322,15 @@ pub(super) async fn delete_user(
 
     cfg.validate()
         .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
-    let revision = save_config_to_disk(&shared.config_path, &cfg).await?;
+    let touched_sections = [
+        AccessSection::Users,
+        AccessSection::UserAdTags,
+        AccessSection::UserMaxTcpConns,
+        AccessSection::UserExpirations,
+        AccessSection::UserDataQuota,
+        AccessSection::UserMaxUniqueIps,
+    ];
+    let revision = save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
     drop(_guard);
     shared.ip_tracker.remove_user_limit(user).await;
     shared.ip_tracker.clear_user_ips(user).await;
@@ -343,7 +386,16 @@ pub(super) async fn users_from_config(
                 .get(&username)
                 .map(chrono::DateTime::<chrono::Utc>::to_rfc3339),
             data_quota_bytes: cfg.access.user_data_quota.get(&username).copied(),
-            max_unique_ips: cfg.access.user_max_unique_ips.get(&username).copied(),
+            max_unique_ips: cfg
+                .access
+                .user_max_unique_ips
+                .get(&username)
+                .copied()
+                .filter(|limit| *limit > 0)
+                .or(
+                    (cfg.access.user_max_unique_ips_global_each > 0)
+                        .then_some(cfg.access.user_max_unique_ips_global_each),
+                ),
             current_connections: stats.get_user_curr_connects(&username),
             active_unique_ips: active_ip_list.len(),
             active_unique_ips_list: active_ip_list,
@@ -418,17 +470,6 @@ fn resolve_link_hosts(
         return vec![host.to_string()];
     }
 
-    let mut startup_hosts = Vec::new();
-    if let Some(ip) = startup_detected_ip_v4 {
-        push_unique_host(&mut startup_hosts, &ip.to_string());
-    }
-    if let Some(ip) = startup_detected_ip_v6 {
-        push_unique_host(&mut startup_hosts, &ip.to_string());
-    }
-    if !startup_hosts.is_empty() {
-        return startup_hosts;
-    }
-
     let mut hosts = Vec::new();
     for listener in &cfg.server.listeners {
         if let Some(host) = listener
@@ -443,24 +484,44 @@ fn resolve_link_hosts(
         if let Some(ip) = listener.announce_ip {
             if !ip.is_unspecified() {
                 push_unique_host(&mut hosts, &ip.to_string());
+                continue;
+            }
+        }
+        if listener.ip.is_unspecified() {
+            let detected_ip = if listener.ip.is_ipv4() {
+                startup_detected_ip_v4
+            } else {
+                startup_detected_ip_v6
+            };
+            if let Some(ip) = detected_ip {
+                push_unique_host(&mut hosts, &ip.to_string());
+            } else {
+                push_unique_host(&mut hosts, &listener.ip.to_string());
             }
             continue;
         }
-        if !listener.ip.is_unspecified() {
-            push_unique_host(&mut hosts, &listener.ip.to_string());
-        }
+        push_unique_host(&mut hosts, &listener.ip.to_string());
     }
 
-    if hosts.is_empty() {
-        if let Some(host) = cfg.server.listen_addr_ipv4.as_deref() {
-            push_host_from_legacy_listen(&mut hosts, host);
-        }
-        if let Some(host) = cfg.server.listen_addr_ipv6.as_deref() {
-            push_host_from_legacy_listen(&mut hosts, host);
-        }
+    if !hosts.is_empty() {
+        return hosts;
     }
 
-    hosts
+    if let Some(ip) = startup_detected_ip_v4.or(startup_detected_ip_v6) {
+        return vec![ip.to_string()];
+    }
+
+    if let Some(host) = cfg.server.listen_addr_ipv4.as_deref() {
+        push_host_from_legacy_listen(&mut hosts, host);
+    }
+    if let Some(host) = cfg.server.listen_addr_ipv6.as_deref() {
+        push_host_from_legacy_listen(&mut hosts, host);
+    }
+    if !hosts.is_empty() {
+        return hosts;
+    }
+
+    vec!["UNKNOWN".to_string()]
 }
 
 fn push_host_from_legacy_listen(hosts: &mut Vec<String>, raw: &str) {

src/config/defaults.rs

@@ -21,6 +21,21 @@ const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_ACTIVE_WRITERS_PER_CORE: u16 = 64;
 const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_WARM_WRITERS_PER_CORE: u16 = 64;
 const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_ACTIVE_WRITERS_GLOBAL: u32 = 256;
 const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_WARM_WRITERS_GLOBAL: u32 = 256;
+const DEFAULT_ME_WRITER_CMD_CHANNEL_CAPACITY: usize = 4096;
+const DEFAULT_ME_ROUTE_CHANNEL_CAPACITY: usize = 768;
+const DEFAULT_ME_C2ME_CHANNEL_CAPACITY: usize = 1024;
+const DEFAULT_ME_READER_ROUTE_DATA_WAIT_MS: u64 = 2;
+const DEFAULT_ME_D2C_FLUSH_BATCH_MAX_FRAMES: usize = 32;
+const DEFAULT_ME_D2C_FLUSH_BATCH_MAX_BYTES: usize = 128 * 1024;
+const DEFAULT_ME_D2C_FLUSH_BATCH_MAX_DELAY_US: u64 = 1500;
+const DEFAULT_ME_D2C_ACK_FLUSH_IMMEDIATE: bool = false;
+const DEFAULT_DIRECT_RELAY_COPY_BUF_C2S_BYTES: usize = 64 * 1024;
+const DEFAULT_DIRECT_RELAY_COPY_BUF_S2C_BYTES: usize = 256 * 1024;
+const DEFAULT_ME_WRITER_PICK_SAMPLE_SIZE: u8 = 3;
+const DEFAULT_ME_HEALTH_INTERVAL_MS_UNHEALTHY: u64 = 1000;
+const DEFAULT_ME_HEALTH_INTERVAL_MS_HEALTHY: u64 = 3000;
+const DEFAULT_ME_ADMISSION_POLL_MS: u64 = 1000;
+const DEFAULT_ME_WARN_RATE_LIMIT_MS: u64 = 5000;
 const DEFAULT_USER_MAX_UNIQUE_IPS_WINDOW_SECS: u64 = 30;
 const DEFAULT_UPSTREAM_CONNECT_RETRY_ATTEMPTS: u32 = 2;
 const DEFAULT_UPSTREAM_UNHEALTHY_FAIL_THRESHOLD: u32 = 5;
@@ -104,11 +119,11 @@ pub(crate) fn default_metrics_whitelist() -> Vec<IpNetwork> {
 }
 
 pub(crate) fn default_api_listen() -> String {
-    "127.0.0.1:9091".to_string()
+    "0.0.0.0:9091".to_string()
 }
 
 pub(crate) fn default_api_whitelist() -> Vec<IpNetwork> {
-    default_metrics_whitelist()
+    vec!["127.0.0.0/8".parse().unwrap()]
 }
 
 pub(crate) fn default_api_request_body_limit_bytes() -> usize {
@@ -116,7 +131,7 @@ pub(crate) fn default_api_request_body_limit_bytes() -> usize {
 }
 
 pub(crate) fn default_api_minimal_runtime_enabled() -> bool {
-    false
+    true
 }
 
 pub(crate) fn default_api_minimal_runtime_cache_ttl_ms() -> u64 {
@@ -132,6 +147,10 @@ pub(crate) fn default_proxy_protocol_header_timeout_ms() -> u64 {
     500
 }
 
+pub(crate) fn default_server_max_connections() -> u32 {
+    10_000
+}
+
 pub(crate) fn default_prefer_4() -> u8 {
     4
 }
@@ -296,6 +315,66 @@ pub(crate) fn default_me_adaptive_floor_max_warm_writers_global() -> u32 {
     DEFAULT_ME_ADAPTIVE_FLOOR_MAX_WARM_WRITERS_GLOBAL
 }
 
+pub(crate) fn default_me_writer_cmd_channel_capacity() -> usize {
+    DEFAULT_ME_WRITER_CMD_CHANNEL_CAPACITY
+}
+
+pub(crate) fn default_me_route_channel_capacity() -> usize {
+    DEFAULT_ME_ROUTE_CHANNEL_CAPACITY
+}
+
+pub(crate) fn default_me_c2me_channel_capacity() -> usize {
+    DEFAULT_ME_C2ME_CHANNEL_CAPACITY
+}
+
+pub(crate) fn default_me_reader_route_data_wait_ms() -> u64 {
+    DEFAULT_ME_READER_ROUTE_DATA_WAIT_MS
+}
+
+pub(crate) fn default_me_d2c_flush_batch_max_frames() -> usize {
+    DEFAULT_ME_D2C_FLUSH_BATCH_MAX_FRAMES
+}
+
+pub(crate) fn default_me_d2c_flush_batch_max_bytes() -> usize {
+    DEFAULT_ME_D2C_FLUSH_BATCH_MAX_BYTES
+}
+
+pub(crate) fn default_me_d2c_flush_batch_max_delay_us() -> u64 {
+    DEFAULT_ME_D2C_FLUSH_BATCH_MAX_DELAY_US
+}
+
+pub(crate) fn default_me_d2c_ack_flush_immediate() -> bool {
+    DEFAULT_ME_D2C_ACK_FLUSH_IMMEDIATE
+}
+
+pub(crate) fn default_direct_relay_copy_buf_c2s_bytes() -> usize {
+    DEFAULT_DIRECT_RELAY_COPY_BUF_C2S_BYTES
+}
+
+pub(crate) fn default_direct_relay_copy_buf_s2c_bytes() -> usize {
+    DEFAULT_DIRECT_RELAY_COPY_BUF_S2C_BYTES
+}
+
+pub(crate) fn default_me_writer_pick_sample_size() -> u8 {
+    DEFAULT_ME_WRITER_PICK_SAMPLE_SIZE
+}
+
+pub(crate) fn default_me_health_interval_ms_unhealthy() -> u64 {
+    DEFAULT_ME_HEALTH_INTERVAL_MS_UNHEALTHY
+}
+
+pub(crate) fn default_me_health_interval_ms_healthy() -> u64 {
+    DEFAULT_ME_HEALTH_INTERVAL_MS_HEALTHY
+}
+
+pub(crate) fn default_me_admission_poll_ms() -> u64 {
+    DEFAULT_ME_ADMISSION_POLL_MS
+}
+
+pub(crate) fn default_me_warn_rate_limit_ms() -> u64 {
+    DEFAULT_ME_WARN_RATE_LIMIT_MS
+}
+
 pub(crate) fn default_upstream_connect_retry_attempts() -> u32 {
     DEFAULT_UPSTREAM_CONNECT_RETRY_ATTEMPTS
 }
@@ -509,6 +588,10 @@ pub(crate) fn default_me_pool_drain_ttl_secs() -> u64 {
     90
 }
 
+pub(crate) fn default_me_pool_drain_threshold() -> u64 {
+    128
+}
+
 pub(crate) fn default_me_bind_stale_ttl_secs() -> u64 {
     default_me_pool_drain_ttl_secs()
 }
@@ -560,6 +643,10 @@ pub(crate) fn default_user_max_unique_ips_window_secs() -> u64 {
     DEFAULT_USER_MAX_UNIQUE_IPS_WINDOW_SECS
 }
 
+pub(crate) fn default_user_max_unique_ips_global_each() -> usize {
+    0
+}
+
 // Custom deserializer helpers
 
 #[derive(Deserialize)]

src/config/hot_reload.rs

@@ -21,16 +21,24 @@
 //! `network.*`, `use_middle_proxy`) are **not** applied; a warning is emitted.
 //! Non-hot changes are never mixed into the runtime config snapshot.
 
+use std::collections::BTreeSet;
 use std::net::IpAddr;
-use std::path::PathBuf;
-use std::sync::Arc;
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, RwLock as StdRwLock};
+use std::time::Duration;
 
 use notify::{EventKind, RecursiveMode, Watcher, recommended_watcher};
 use tokio::sync::{mpsc, watch};
 use tracing::{error, info, warn};
 
-use crate::config::{LogLevel, MeBindStaleMode, MeFloorMode, MeSocksKdfPolicy, MeTelemetryLevel};
-use super::load::ProxyConfig;
+use crate::config::{
+    LogLevel, MeBindStaleMode, MeFloorMode, MeSocksKdfPolicy, MeTelemetryLevel,
+    MeWriterPickMode,
+};
+use super::load::{LoadedConfig, ProxyConfig};
+
+const HOT_RELOAD_STABLE_SNAPSHOTS: u8 = 2;
+const HOT_RELOAD_DEBOUNCE: Duration = Duration::from_millis(50);
 
 // ── Hot fields ────────────────────────────────────────────────────────────────
 
@@ -47,6 +55,7 @@ pub struct HotFields {
     pub me_reinit_coalesce_window_ms: u64,
     pub hardswap:                bool,
     pub me_pool_drain_ttl_secs:  u64,
+    pub me_pool_drain_threshold: u64,
     pub me_pool_min_fresh_ratio: f32,
     pub me_reinit_drain_timeout_secs: u64,
     pub me_hardswap_warmup_delay_min_ms: u64,
@@ -57,6 +66,8 @@ pub struct HotFields {
     pub me_bind_stale_ttl_secs: u64,
     pub me_secret_atomic_snapshot: bool,
     pub me_deterministic_writer_sort: bool,
+    pub me_writer_pick_mode: MeWriterPickMode,
+    pub me_writer_pick_sample_size: u8,
     pub me_single_endpoint_shadow_writers: u8,
     pub me_single_endpoint_outage_mode_enabled: bool,
     pub me_single_endpoint_outage_disable_quarantine: bool,
@@ -91,12 +102,24 @@ pub struct HotFields {
     pub me_route_backpressure_base_timeout_ms: u64,
     pub me_route_backpressure_high_timeout_ms: u64,
     pub me_route_backpressure_high_watermark_pct: u8,
+    pub me_reader_route_data_wait_ms: u64,
+    pub me_d2c_flush_batch_max_frames: usize,
+    pub me_d2c_flush_batch_max_bytes: usize,
+    pub me_d2c_flush_batch_max_delay_us: u64,
+    pub me_d2c_ack_flush_immediate: bool,
+    pub direct_relay_copy_buf_c2s_bytes: usize,
+    pub direct_relay_copy_buf_s2c_bytes: usize,
+    pub me_health_interval_ms_unhealthy: u64,
+    pub me_health_interval_ms_healthy: u64,
+    pub me_admission_poll_ms: u64,
+    pub me_warn_rate_limit_ms: u64,
     pub users:                   std::collections::HashMap<String, String>,
     pub user_ad_tags:            std::collections::HashMap<String, String>,
     pub user_max_tcp_conns:      std::collections::HashMap<String, usize>,
     pub user_expirations:        std::collections::HashMap<String, chrono::DateTime<chrono::Utc>>,
     pub user_data_quota:         std::collections::HashMap<String, u64>,
     pub user_max_unique_ips:     std::collections::HashMap<String, usize>,
+    pub user_max_unique_ips_global_each: usize,
     pub user_max_unique_ips_mode: crate::config::UserMaxUniqueIpsMode,
     pub user_max_unique_ips_window_secs: u64,
 }
@@ -114,6 +137,7 @@ impl HotFields {
             me_reinit_coalesce_window_ms: cfg.general.me_reinit_coalesce_window_ms,
             hardswap:                cfg.general.hardswap,
             me_pool_drain_ttl_secs:  cfg.general.me_pool_drain_ttl_secs,
+            me_pool_drain_threshold: cfg.general.me_pool_drain_threshold,
             me_pool_min_fresh_ratio: cfg.general.me_pool_min_fresh_ratio,
             me_reinit_drain_timeout_secs: cfg.general.me_reinit_drain_timeout_secs,
             me_hardswap_warmup_delay_min_ms: cfg.general.me_hardswap_warmup_delay_min_ms,
@@ -126,6 +150,8 @@ impl HotFields {
             me_bind_stale_ttl_secs: cfg.general.me_bind_stale_ttl_secs,
             me_secret_atomic_snapshot: cfg.general.me_secret_atomic_snapshot,
             me_deterministic_writer_sort: cfg.general.me_deterministic_writer_sort,
+            me_writer_pick_mode: cfg.general.me_writer_pick_mode,
+            me_writer_pick_sample_size: cfg.general.me_writer_pick_sample_size,
             me_single_endpoint_shadow_writers: cfg.general.me_single_endpoint_shadow_writers,
             me_single_endpoint_outage_mode_enabled: cfg
                 .general
@@ -192,12 +218,24 @@ impl HotFields {
             me_route_backpressure_base_timeout_ms: cfg.general.me_route_backpressure_base_timeout_ms,
             me_route_backpressure_high_timeout_ms: cfg.general.me_route_backpressure_high_timeout_ms,
             me_route_backpressure_high_watermark_pct: cfg.general.me_route_backpressure_high_watermark_pct,
+            me_reader_route_data_wait_ms: cfg.general.me_reader_route_data_wait_ms,
+            me_d2c_flush_batch_max_frames: cfg.general.me_d2c_flush_batch_max_frames,
+            me_d2c_flush_batch_max_bytes: cfg.general.me_d2c_flush_batch_max_bytes,
+            me_d2c_flush_batch_max_delay_us: cfg.general.me_d2c_flush_batch_max_delay_us,
+            me_d2c_ack_flush_immediate: cfg.general.me_d2c_ack_flush_immediate,
+            direct_relay_copy_buf_c2s_bytes: cfg.general.direct_relay_copy_buf_c2s_bytes,
+            direct_relay_copy_buf_s2c_bytes: cfg.general.direct_relay_copy_buf_s2c_bytes,
+            me_health_interval_ms_unhealthy: cfg.general.me_health_interval_ms_unhealthy,
+            me_health_interval_ms_healthy: cfg.general.me_health_interval_ms_healthy,
+            me_admission_poll_ms: cfg.general.me_admission_poll_ms,
+            me_warn_rate_limit_ms: cfg.general.me_warn_rate_limit_ms,
             users:                   cfg.access.users.clone(),
             user_ad_tags:            cfg.access.user_ad_tags.clone(),
             user_max_tcp_conns:      cfg.access.user_max_tcp_conns.clone(),
             user_expirations:        cfg.access.user_expirations.clone(),
             user_data_quota:         cfg.access.user_data_quota.clone(),
             user_max_unique_ips:     cfg.access.user_max_unique_ips.clone(),
+            user_max_unique_ips_global_each: cfg.access.user_max_unique_ips_global_each,
             user_max_unique_ips_mode: cfg.access.user_max_unique_ips_mode,
             user_max_unique_ips_window_secs: cfg.access.user_max_unique_ips_window_secs,
         }
@@ -258,6 +296,149 @@ fn listeners_equal(
     })
 }
 
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+struct WatchManifest {
+    files: BTreeSet<PathBuf>,
+    dirs: BTreeSet<PathBuf>,
+}
+
+impl WatchManifest {
+    fn from_source_files(source_files: &[PathBuf]) -> Self {
+        let mut files = BTreeSet::new();
+        let mut dirs = BTreeSet::new();
+
+        for path in source_files {
+            let normalized = normalize_watch_path(path);
+            files.insert(normalized.clone());
+            if let Some(parent) = normalized.parent() {
+                dirs.insert(parent.to_path_buf());
+            }
+        }
+
+        Self { files, dirs }
+    }
+
+    fn matches_event_paths(&self, event_paths: &[PathBuf]) -> bool {
+        event_paths
+            .iter()
+            .map(|path| normalize_watch_path(path))
+            .any(|path| self.files.contains(&path))
+    }
+}
+
+#[derive(Debug, Default)]
+struct ReloadState {
+    applied_snapshot_hash: Option<u64>,
+    candidate_snapshot_hash: Option<u64>,
+    candidate_hits: u8,
+}
+
+impl ReloadState {
+    fn new(applied_snapshot_hash: Option<u64>) -> Self {
+        Self {
+            applied_snapshot_hash,
+            candidate_snapshot_hash: None,
+            candidate_hits: 0,
+        }
+    }
+
+    fn is_applied(&self, hash: u64) -> bool {
+        self.applied_snapshot_hash == Some(hash)
+    }
+
+    fn observe_candidate(&mut self, hash: u64) -> u8 {
+        if self.candidate_snapshot_hash == Some(hash) {
+            self.candidate_hits = self.candidate_hits.saturating_add(1);
+        } else {
+            self.candidate_snapshot_hash = Some(hash);
+            self.candidate_hits = 1;
+        }
+        self.candidate_hits
+    }
+
+    fn reset_candidate(&mut self) {
+        self.candidate_snapshot_hash = None;
+        self.candidate_hits = 0;
+    }
+
+    fn mark_applied(&mut self, hash: u64) {
+        self.applied_snapshot_hash = Some(hash);
+        self.reset_candidate();
+    }
+}
+
+fn normalize_watch_path(path: &Path) -> PathBuf {
+    path.canonicalize().unwrap_or_else(|_| {
+        if path.is_absolute() {
+            path.to_path_buf()
+        } else {
+            std::env::current_dir()
+                .map(|cwd| cwd.join(path))
+                .unwrap_or_else(|_| path.to_path_buf())
+        }
+    })
+}
+
+fn sync_watch_paths<W: Watcher>(
+    watcher: &mut W,
+    current: &BTreeSet<PathBuf>,
+    next: &BTreeSet<PathBuf>,
+    recursive_mode: RecursiveMode,
+    kind: &str,
+) {
+    for path in current.difference(next) {
+        if let Err(e) = watcher.unwatch(path) {
+            warn!(path = %path.display(), error = %e, "config watcher: failed to unwatch {kind}");
+        }
+    }
+
+    for path in next.difference(current) {
+        if let Err(e) = watcher.watch(path, recursive_mode) {
+            warn!(path = %path.display(), error = %e, "config watcher: failed to watch {kind}");
+        }
+    }
+}
+
+fn apply_watch_manifest<W1: Watcher, W2: Watcher>(
+    notify_watcher: Option<&mut W1>,
+    poll_watcher: Option<&mut W2>,
+    manifest_state: &Arc<StdRwLock<WatchManifest>>,
+    next_manifest: WatchManifest,
+) {
+    let current_manifest = manifest_state
+        .read()
+        .map(|manifest| manifest.clone())
+        .unwrap_or_default();
+
+    if current_manifest == next_manifest {
+        return;
+    }
+
+    if let Some(watcher) = notify_watcher {
+        sync_watch_paths(
+            watcher,
+            &current_manifest.dirs,
+            &next_manifest.dirs,
+            RecursiveMode::NonRecursive,
+            "config directory",
+        );
+    }
+
+    if let Some(watcher) = poll_watcher {
+        sync_watch_paths(
+            watcher,
+            &current_manifest.files,
+            &next_manifest.files,
+            RecursiveMode::NonRecursive,
+            "config file",
+        );
+    }
+
+    if let Ok(mut manifest) = manifest_state.write() {
+        *manifest = next_manifest;
+    }
+}
+
 fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
     let mut cfg = old.clone();
 
@@ -273,6 +454,7 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
     cfg.general.me_reinit_coalesce_window_ms = new.general.me_reinit_coalesce_window_ms;
     cfg.general.hardswap = new.general.hardswap;
     cfg.general.me_pool_drain_ttl_secs = new.general.me_pool_drain_ttl_secs;
+    cfg.general.me_pool_drain_threshold = new.general.me_pool_drain_threshold;
     cfg.general.me_pool_min_fresh_ratio = new.general.me_pool_min_fresh_ratio;
     cfg.general.me_reinit_drain_timeout_secs = new.general.me_reinit_drain_timeout_secs;
     cfg.general.me_hardswap_warmup_delay_min_ms = new.general.me_hardswap_warmup_delay_min_ms;
@@ -284,6 +466,8 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
     cfg.general.me_bind_stale_ttl_secs = new.general.me_bind_stale_ttl_secs;
     cfg.general.me_secret_atomic_snapshot = new.general.me_secret_atomic_snapshot;
     cfg.general.me_deterministic_writer_sort = new.general.me_deterministic_writer_sort;
+    cfg.general.me_writer_pick_mode = new.general.me_writer_pick_mode;
+    cfg.general.me_writer_pick_sample_size = new.general.me_writer_pick_sample_size;
     cfg.general.me_single_endpoint_shadow_writers = new.general.me_single_endpoint_shadow_writers;
     cfg.general.me_single_endpoint_outage_mode_enabled =
         new.general.me_single_endpoint_outage_mode_enabled;
@@ -335,6 +519,17 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
         new.general.me_route_backpressure_high_timeout_ms;
     cfg.general.me_route_backpressure_high_watermark_pct =
         new.general.me_route_backpressure_high_watermark_pct;
+    cfg.general.me_reader_route_data_wait_ms = new.general.me_reader_route_data_wait_ms;
+    cfg.general.me_d2c_flush_batch_max_frames = new.general.me_d2c_flush_batch_max_frames;
+    cfg.general.me_d2c_flush_batch_max_bytes = new.general.me_d2c_flush_batch_max_bytes;
+    cfg.general.me_d2c_flush_batch_max_delay_us = new.general.me_d2c_flush_batch_max_delay_us;
+    cfg.general.me_d2c_ack_flush_immediate = new.general.me_d2c_ack_flush_immediate;
+    cfg.general.direct_relay_copy_buf_c2s_bytes = new.general.direct_relay_copy_buf_c2s_bytes;
+    cfg.general.direct_relay_copy_buf_s2c_bytes = new.general.direct_relay_copy_buf_s2c_bytes;
+    cfg.general.me_health_interval_ms_unhealthy = new.general.me_health_interval_ms_unhealthy;
+    cfg.general.me_health_interval_ms_healthy = new.general.me_health_interval_ms_healthy;
+    cfg.general.me_admission_poll_ms = new.general.me_admission_poll_ms;
+    cfg.general.me_warn_rate_limit_ms = new.general.me_warn_rate_limit_ms;
 
     cfg.access.users = new.access.users.clone();
     cfg.access.user_ad_tags = new.access.user_ad_tags.clone();
@@ -342,6 +537,7 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
     cfg.access.user_expirations = new.access.user_expirations.clone();
     cfg.access.user_data_quota = new.access.user_data_quota.clone();
     cfg.access.user_max_unique_ips = new.access.user_max_unique_ips.clone();
+    cfg.access.user_max_unique_ips_global_each = new.access.user_max_unique_ips_global_each;
     cfg.access.user_max_unique_ips_mode = new.access.user_max_unique_ips_mode;
     cfg.access.user_max_unique_ips_window_secs = new.access.user_max_unique_ips_window_secs;
 
@@ -633,6 +829,13 @@ fn log_changes(
         );
     }
 
+    if old_hot.me_pool_drain_threshold != new_hot.me_pool_drain_threshold {
+        info!(
+            "config reload: me_pool_drain_threshold: {} → {}",
+            old_hot.me_pool_drain_threshold, new_hot.me_pool_drain_threshold,
+        );
+    }
+
     if (old_hot.me_pool_min_fresh_ratio - new_hot.me_pool_min_fresh_ratio).abs() > f32::EPSILON {
         info!(
             "config reload: me_pool_min_fresh_ratio: {:.3} → {:.3}",
@@ -671,11 +874,15 @@ fn log_changes(
     }
     if old_hot.me_secret_atomic_snapshot != new_hot.me_secret_atomic_snapshot
         || old_hot.me_deterministic_writer_sort != new_hot.me_deterministic_writer_sort
+        || old_hot.me_writer_pick_mode != new_hot.me_writer_pick_mode
+        || old_hot.me_writer_pick_sample_size != new_hot.me_writer_pick_sample_size
     {
         info!(
-            "config reload: me_runtime_flags: secret_atomic_snapshot={} deterministic_sort={}",
+            "config reload: me_runtime_flags: secret_atomic_snapshot={} deterministic_sort={} writer_pick_mode={:?} writer_pick_sample_size={}",
             new_hot.me_secret_atomic_snapshot,
-            new_hot.me_deterministic_writer_sort
+            new_hot.me_deterministic_writer_sort,
+            new_hot.me_writer_pick_mode,
+            new_hot.me_writer_pick_sample_size,
         );
     }
     if old_hot.me_single_endpoint_shadow_writers != new_hot.me_single_endpoint_shadow_writers
@@ -796,12 +1003,41 @@ fn log_changes(
             != new_hot.me_route_backpressure_high_timeout_ms
         || old_hot.me_route_backpressure_high_watermark_pct
             != new_hot.me_route_backpressure_high_watermark_pct
+        || old_hot.me_reader_route_data_wait_ms != new_hot.me_reader_route_data_wait_ms
+        || old_hot.me_health_interval_ms_unhealthy
+            != new_hot.me_health_interval_ms_unhealthy
+        || old_hot.me_health_interval_ms_healthy != new_hot.me_health_interval_ms_healthy
+        || old_hot.me_admission_poll_ms != new_hot.me_admission_poll_ms
+        || old_hot.me_warn_rate_limit_ms != new_hot.me_warn_rate_limit_ms
     {
         info!(
-            "config reload: me_route_backpressure: base={}ms high={}ms watermark={}%",
+            "config reload: me_route_backpressure: base={}ms high={}ms watermark={}%; me_reader_route_data_wait_ms={}; me_health_interval: unhealthy={}ms healthy={}ms; me_admission_poll={}ms; me_warn_rate_limit={}ms",
             new_hot.me_route_backpressure_base_timeout_ms,
             new_hot.me_route_backpressure_high_timeout_ms,
             new_hot.me_route_backpressure_high_watermark_pct,
+            new_hot.me_reader_route_data_wait_ms,
+            new_hot.me_health_interval_ms_unhealthy,
+            new_hot.me_health_interval_ms_healthy,
+            new_hot.me_admission_poll_ms,
+            new_hot.me_warn_rate_limit_ms,
+        );
+    }
+
+    if old_hot.me_d2c_flush_batch_max_frames != new_hot.me_d2c_flush_batch_max_frames
+        || old_hot.me_d2c_flush_batch_max_bytes != new_hot.me_d2c_flush_batch_max_bytes
+        || old_hot.me_d2c_flush_batch_max_delay_us != new_hot.me_d2c_flush_batch_max_delay_us
+        || old_hot.me_d2c_ack_flush_immediate != new_hot.me_d2c_ack_flush_immediate
+        || old_hot.direct_relay_copy_buf_c2s_bytes != new_hot.direct_relay_copy_buf_c2s_bytes
+        || old_hot.direct_relay_copy_buf_s2c_bytes != new_hot.direct_relay_copy_buf_s2c_bytes
+    {
+        info!(
+            "config reload: relay_tuning: me_d2c_frames={} me_d2c_bytes={} me_d2c_delay_us={} me_ack_flush_immediate={} direct_buf_c2s={} direct_buf_s2c={}",
+            new_hot.me_d2c_flush_batch_max_frames,
+            new_hot.me_d2c_flush_batch_max_bytes,
+            new_hot.me_d2c_flush_batch_max_delay_us,
+            new_hot.me_d2c_ack_flush_immediate,
+            new_hot.direct_relay_copy_buf_c2s_bytes,
+            new_hot.direct_relay_copy_buf_s2c_bytes,
         );
     }
 
@@ -876,12 +1112,14 @@ fn log_changes(
             new_hot.user_max_unique_ips.len()
         );
     }
-    if old_hot.user_max_unique_ips_mode != new_hot.user_max_unique_ips_mode
+    if old_hot.user_max_unique_ips_global_each != new_hot.user_max_unique_ips_global_each
+        || old_hot.user_max_unique_ips_mode != new_hot.user_max_unique_ips_mode
         || old_hot.user_max_unique_ips_window_secs
             != new_hot.user_max_unique_ips_window_secs
     {
         info!(
-            "config reload: user_max_unique_ips policy mode={:?} window={}s",
+            "config reload: user_max_unique_ips policy global_each={} mode={:?} window={}s",
+            new_hot.user_max_unique_ips_global_each,
             new_hot.user_max_unique_ips_mode,
             new_hot.user_max_unique_ips_window_secs
         );
@@ -895,18 +1133,42 @@ fn reload_config(
     log_tx: &watch::Sender<LogLevel>,
     detected_ip_v4: Option<IpAddr>,
     detected_ip_v6: Option<IpAddr>,
-) {
-    let new_cfg = match ProxyConfig::load(config_path) {
-        Ok(c) => c,
+    reload_state: &mut ReloadState,
+) -> Option<WatchManifest> {
+    let loaded = match ProxyConfig::load_with_metadata(config_path) {
+        Ok(loaded) => loaded,
         Err(e) => {
+            reload_state.reset_candidate();
             error!("config reload: failed to parse {:?}: {}", config_path, e);
-            return;
+            return None;
         }
     };
+    let LoadedConfig {
+        config: new_cfg,
+        source_files,
+        rendered_hash,
+    } = loaded;
+    let next_manifest = WatchManifest::from_source_files(&source_files);
 
     if let Err(e) = new_cfg.validate() {
+        reload_state.reset_candidate();
         error!("config reload: validation failed: {}; keeping old config", e);
-        return;
+        return Some(next_manifest);
+    }
+
+    if reload_state.is_applied(rendered_hash) {
+        return Some(next_manifest);
+    }
+
+    let candidate_hits = reload_state.observe_candidate(rendered_hash);
+    if candidate_hits < HOT_RELOAD_STABLE_SNAPSHOTS {
+        info!(
+            snapshot_hash = rendered_hash,
+            candidate_hits,
+            required_hits = HOT_RELOAD_STABLE_SNAPSHOTS,
+            "config reload: candidate snapshot observed but not stable yet"
+        );
+        return Some(next_manifest);
     }
 
     let old_cfg = config_tx.borrow().clone();
@@ -921,17 +1183,19 @@ fn reload_config(
     }
 
     if !hot_changed {
-        return;
+        reload_state.mark_applied(rendered_hash);
+        return Some(next_manifest);
     }
 
     if old_hot.dns_overrides != applied_hot.dns_overrides
         && let Err(e) = crate::network::dns_overrides::install_entries(&applied_hot.dns_overrides)
     {
+        reload_state.reset_candidate();
         error!(
             "config reload: invalid network.dns_overrides: {}; keeping old config",
             e
         );
-        return;
+        return Some(next_manifest);
     }
 
     log_changes(
@@ -943,6 +1207,8 @@ fn reload_config(
         detected_ip_v6,
     );
     config_tx.send(Arc::new(applied_cfg)).ok();
+    reload_state.mark_applied(rendered_hash);
+    Some(next_manifest)
 }
 
 // ── Public API ────────────────────────────────────────────────────────────────
@@ -965,80 +1231,86 @@ pub fn spawn_config_watcher(
     let (config_tx, config_rx) = watch::channel(initial);
     let (log_tx, log_rx)       = watch::channel(initial_level);
 
-    // Bridge: sync notify callbacks → async task via mpsc.
-    let (notify_tx, mut notify_rx) = mpsc::channel::<()>(4);
+    let config_path = normalize_watch_path(&config_path);
+    let initial_loaded = ProxyConfig::load_with_metadata(&config_path).ok();
+    let initial_manifest = initial_loaded
+        .as_ref()
+        .map(|loaded| WatchManifest::from_source_files(&loaded.source_files))
+        .unwrap_or_else(|| WatchManifest::from_source_files(std::slice::from_ref(&config_path)));
+    let initial_snapshot_hash = initial_loaded.as_ref().map(|loaded| loaded.rendered_hash);
 
-    // Canonicalize so path matches what notify returns (absolute) in events.
-    let config_path = match config_path.canonicalize() {
-        Ok(p) => p,
-        Err(_) => config_path.to_path_buf(),
-    };
-
-    // Watch the parent directory rather than the file itself, because many
-    // editors (vim, nano) and systemd write via rename, which would cause
-    // inotify to lose track of the original inode.
-    let watch_dir = config_path
-        .parent()
-        .unwrap_or_else(|| std::path::Path::new("."))
-        .to_path_buf();
-
-    // ── inotify watcher (instant on local fs) ────────────────────────────
-    let config_file = config_path.clone();
-    let tx_inotify  = notify_tx.clone();
-    let inotify_ok = match recommended_watcher(move |res: notify::Result<notify::Event>| {
-        let Ok(event) = res else { return };
-        let is_our_file = event.paths.iter().any(|p| p == &config_file);
-        if !is_our_file { return; }
-        if matches!(event.kind, EventKind::Modify(_) | EventKind::Create(_) | EventKind::Remove(_)) {
-            let _ = tx_inotify.try_send(());
-        }
-    }) {
-        Ok(mut w) => match w.watch(&watch_dir, RecursiveMode::NonRecursive) {
-            Ok(()) => {
-                info!("config watcher: inotify active on {:?}", config_path);
-                Box::leak(Box::new(w));
-                true
-            }
-            Err(e) => { warn!("config watcher: inotify watch failed: {}", e); false }
-        },
-        Err(e) => { warn!("config watcher: inotify unavailable: {}", e); false }
-    };
-
-    // ── poll watcher (always active, fixes Docker bind mounts / NFS) ─────
-    // inotify does not receive events for files mounted from the host into
-    // a container. PollWatcher compares file contents every 3 s and fires
-    // on any change regardless of the underlying fs.
-    let config_file2 = config_path.clone();
-    let tx_poll      = notify_tx.clone();
-    match notify::poll::PollWatcher::new(
-        move |res: notify::Result<notify::Event>| {
-            let Ok(event) = res else { return };
-            let is_our_file = event.paths.iter().any(|p| p == &config_file2);
-            if !is_our_file { return; }
-            if matches!(event.kind, EventKind::Modify(_) | EventKind::Create(_) | EventKind::Remove(_)) {
-                let _ = tx_poll.try_send(());
-            }
-        },
-        notify::Config::default()
-            .with_poll_interval(std::time::Duration::from_secs(3))
-            .with_compare_contents(true),
-    ) {
-        Ok(mut w) => match w.watch(&config_path, RecursiveMode::NonRecursive) {
-            Ok(()) => {
-                if inotify_ok {
-                    info!("config watcher: poll watcher also active (Docker/NFS safe)");
-                } else {
-                    info!("config watcher: poll watcher active on {:?} (3s interval)", config_path);
-                }
-                Box::leak(Box::new(w));
-            }
-            Err(e) => warn!("config watcher: poll watch failed: {}", e),
-        },
-        Err(e) => warn!("config watcher: poll watcher unavailable: {}", e),
-    }
-
-    // ── event loop ───────────────────────────────────────────────────────
     tokio::spawn(async move {
+        let (notify_tx, mut notify_rx) = mpsc::channel::<()>(4);
+        let manifest_state = Arc::new(StdRwLock::new(WatchManifest::default()));
+        let mut reload_state = ReloadState::new(initial_snapshot_hash);
+
+        let tx_inotify = notify_tx.clone();
+        let manifest_for_inotify = manifest_state.clone();
+        let mut inotify_watcher = match recommended_watcher(move |res: notify::Result<notify::Event>| {
+            let Ok(event) = res else { return };
+            if !matches!(event.kind, EventKind::Modify(_) | EventKind::Create(_) | EventKind::Remove(_)) {
+                return;
+            }
+            let is_our_file = manifest_for_inotify
+                .read()
+                .map(|manifest| manifest.matches_event_paths(&event.paths))
+                .unwrap_or(false);
+            if is_our_file {
+                let _ = tx_inotify.try_send(());
+            }
+        }) {
+            Ok(watcher) => Some(watcher),
+            Err(e) => {
+                warn!("config watcher: inotify unavailable: {}", e);
+                None
+            }
+        };
+        apply_watch_manifest(
+            inotify_watcher.as_mut(),
+            Option::<&mut notify::poll::PollWatcher>::None,
+            &manifest_state,
+            initial_manifest.clone(),
+        );
+        if inotify_watcher.is_some() {
+            info!("config watcher: inotify active on {:?}", config_path);
+        }
+
+        let tx_poll = notify_tx.clone();
+        let manifest_for_poll = manifest_state.clone();
+        let mut poll_watcher = match notify::poll::PollWatcher::new(
+            move |res: notify::Result<notify::Event>| {
+                let Ok(event) = res else { return };
+                if !matches!(event.kind, EventKind::Modify(_) | EventKind::Create(_) | EventKind::Remove(_)) {
+                    return;
+                }
+                let is_our_file = manifest_for_poll
+                    .read()
+                    .map(|manifest| manifest.matches_event_paths(&event.paths))
+                    .unwrap_or(false);
+                if is_our_file {
+                    let _ = tx_poll.try_send(());
+                }
+            },
+            notify::Config::default()
+                .with_poll_interval(Duration::from_secs(3))
+                .with_compare_contents(true),
+        ) {
+            Ok(watcher) => Some(watcher),
+            Err(e) => {
+                warn!("config watcher: poll watcher unavailable: {}", e);
+                None
+            }
+        };
+        apply_watch_manifest(
+            Option::<&mut notify::RecommendedWatcher>::None,
+            poll_watcher.as_mut(),
+            &manifest_state,
+            initial_manifest.clone(),
+        );
+        if poll_watcher.is_some() {
+            info!("config watcher: poll watcher active (Docker/NFS safe)");
+        }
+
         #[cfg(unix)]
         let mut sighup = {
             use tokio::signal::unix::{SignalKind, signal};
@@ -1058,11 +1330,25 @@ pub fn spawn_config_watcher(
             #[cfg(not(unix))]
             if notify_rx.recv().await.is_none() { break; }
 
-            // Debounce: drain extra events that arrive within 50 ms.
-            tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+            // Debounce: drain extra events that arrive within a short quiet window.
+            tokio::time::sleep(HOT_RELOAD_DEBOUNCE).await;
             while notify_rx.try_recv().is_ok() {}
 
-            reload_config(&config_path, &config_tx, &log_tx, detected_ip_v4, detected_ip_v6);
+            if let Some(next_manifest) = reload_config(
+                &config_path,
+                &config_tx,
+                &log_tx,
+                detected_ip_v4,
+                detected_ip_v6,
+                &mut reload_state,
+            ) {
+                apply_watch_manifest(
+                    inotify_watcher.as_mut(),
+                    poll_watcher.as_mut(),
+                    &manifest_state,
+                    next_manifest,
+                );
+            }
         }
     });
 
@@ -1077,6 +1363,40 @@ mod tests {
         ProxyConfig::default()
     }
 
+    fn write_reload_config(path: &Path, ad_tag: Option<&str>, server_port: Option<u16>) {
+        let mut config = String::from(
+            r#"
+                [censorship]
+                tls_domain = "example.com"
+
+                [access.users]
+                user = "00000000000000000000000000000000"
+            "#,
+        );
+
+        if ad_tag.is_some() {
+            config.push_str("\n[general]\n");
+            if let Some(tag) = ad_tag {
+                config.push_str(&format!("ad_tag = \"{tag}\"\n"));
+            }
+        }
+
+        if let Some(port) = server_port {
+            config.push_str("\n[server]\n");
+            config.push_str(&format!("port = {port}\n"));
+        }
+
+        std::fs::write(path, config).unwrap();
+    }
+
+    fn temp_config_path(prefix: &str) -> PathBuf {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        std::env::temp_dir().join(format!("{prefix}_{nonce}.toml"))
+    }
+
     #[test]
     fn overlay_applies_hot_and_preserves_non_hot() {
         let old = sample_config();
@@ -1144,4 +1464,61 @@ mod tests {
         assert_eq!(applied.general.use_middle_proxy, old.general.use_middle_proxy);
         assert!(!config_equal(&applied, &new));
     }
+
+    #[test]
+    fn reload_requires_stable_snapshot_before_hot_apply() {
+        let initial_tag = "11111111111111111111111111111111";
+        let final_tag = "22222222222222222222222222222222";
+        let path = temp_config_path("telemt_hot_reload_stable");
+
+        write_reload_config(&path, Some(initial_tag), None);
+        let initial_cfg = Arc::new(ProxyConfig::load(&path).unwrap());
+        let initial_hash = ProxyConfig::load_with_metadata(&path).unwrap().rendered_hash;
+        let (config_tx, _config_rx) = watch::channel(initial_cfg.clone());
+        let (log_tx, _log_rx) = watch::channel(initial_cfg.general.log_level.clone());
+        let mut reload_state = ReloadState::new(Some(initial_hash));
+
+        write_reload_config(&path, None, None);
+        reload_config(&path, &config_tx, &log_tx, None, None, &mut reload_state).unwrap();
+        assert_eq!(
+            config_tx.borrow().general.ad_tag.as_deref(),
+            Some(initial_tag)
+        );
+
+        write_reload_config(&path, Some(final_tag), None);
+        reload_config(&path, &config_tx, &log_tx, None, None, &mut reload_state).unwrap();
+        assert_eq!(
+            config_tx.borrow().general.ad_tag.as_deref(),
+            Some(initial_tag)
+        );
+
+        reload_config(&path, &config_tx, &log_tx, None, None, &mut reload_state).unwrap();
+        assert_eq!(config_tx.borrow().general.ad_tag.as_deref(), Some(final_tag));
+
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn reload_keeps_hot_apply_when_non_hot_fields_change() {
+        let initial_tag = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+        let final_tag = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+        let path = temp_config_path("telemt_hot_reload_mixed");
+
+        write_reload_config(&path, Some(initial_tag), None);
+        let initial_cfg = Arc::new(ProxyConfig::load(&path).unwrap());
+        let initial_hash = ProxyConfig::load_with_metadata(&path).unwrap().rendered_hash;
+        let (config_tx, _config_rx) = watch::channel(initial_cfg.clone());
+        let (log_tx, _log_rx) = watch::channel(initial_cfg.general.log_level.clone());
+        let mut reload_state = ReloadState::new(Some(initial_hash));
+
+        write_reload_config(&path, Some(final_tag), Some(initial_cfg.server.port + 1));
+        reload_config(&path, &config_tx, &log_tx, None, None, &mut reload_state).unwrap();
+        reload_config(&path, &config_tx, &log_tx, None, None, &mut reload_state).unwrap();
+
+        let applied = config_tx.borrow().clone();
+        assert_eq!(applied.general.ad_tag.as_deref(), Some(final_tag));
+        assert_eq!(applied.server.port, initial_cfg.server.port);
+
+        let _ = std::fs::remove_file(path);
+    }
 }

src/config/load.rs

@@ -1,8 +1,9 @@
 #![allow(deprecated)]
 
-use std::collections::HashMap;
+use std::collections::{BTreeSet, HashMap};
+use std::hash::{DefaultHasher, Hash, Hasher};
 use std::net::{IpAddr, SocketAddr};
-use std::path::Path;
+use std::path::{Path, PathBuf};
 
 use rand::Rng;
 use tracing::warn;
@@ -13,7 +14,37 @@ use crate::error::{ProxyError, Result};
 use super::defaults::*;
 use super::types::*;
 
-fn preprocess_includes(content: &str, base_dir: &Path, depth: u8) -> Result<String> {
+#[derive(Debug, Clone)]
+pub(crate) struct LoadedConfig {
+    pub(crate) config: ProxyConfig,
+    pub(crate) source_files: Vec<PathBuf>,
+    pub(crate) rendered_hash: u64,
+}
+
+fn normalize_config_path(path: &Path) -> PathBuf {
+    path.canonicalize().unwrap_or_else(|_| {
+        if path.is_absolute() {
+            path.to_path_buf()
+        } else {
+            std::env::current_dir()
+                .map(|cwd| cwd.join(path))
+                .unwrap_or_else(|_| path.to_path_buf())
+        }
+    })
+}
+
+fn hash_rendered_snapshot(rendered: &str) -> u64 {
+    let mut hasher = DefaultHasher::new();
+    rendered.hash(&mut hasher);
+    hasher.finish()
+}
+
+fn preprocess_includes(
+    content: &str,
+    base_dir: &Path,
+    depth: u8,
+    source_files: &mut BTreeSet<PathBuf>,
+) -> Result<String> {
     if depth > 10 {
         return Err(ProxyError::Config("Include depth > 10".into()));
     }
@@ -25,10 +56,16 @@ fn preprocess_includes(content: &str, base_dir: &Path, depth: u8) -> Result<Stri
             if let Some(rest) = rest.strip_prefix('=') {
                 let path_str = rest.trim().trim_matches('"');
                 let resolved = base_dir.join(path_str);
+                source_files.insert(normalize_config_path(&resolved));
                 let included = std::fs::read_to_string(&resolved)
                     .map_err(|e| ProxyError::Config(e.to_string()))?;
                 let included_dir = resolved.parent().unwrap_or(base_dir);
-                output.push_str(&preprocess_includes(&included, included_dir, depth + 1)?);
+                output.push_str(&preprocess_includes(
+                    &included,
+                    included_dir,
+                    depth + 1,
+                    source_files,
+                )?);
                 output.push('\n');
                 continue;
             }
@@ -138,10 +175,16 @@ pub struct ProxyConfig {
 
 impl ProxyConfig {
     pub fn load<P: AsRef<Path>>(path: P) -> Result<Self> {
-        let content =
-            std::fs::read_to_string(&path).map_err(|e| ProxyError::Config(e.to_string()))?;
-        let base_dir = path.as_ref().parent().unwrap_or(Path::new("."));
-        let processed = preprocess_includes(&content, base_dir, 0)?;
+        Self::load_with_metadata(path).map(|loaded| loaded.config)
+    }
+
+    pub(crate) fn load_with_metadata<P: AsRef<Path>>(path: P) -> Result<LoadedConfig> {
+        let path = path.as_ref();
+        let content = std::fs::read_to_string(path).map_err(|e| ProxyError::Config(e.to_string()))?;
+        let base_dir = path.parent().unwrap_or(Path::new("."));
+        let mut source_files = BTreeSet::new();
+        source_files.insert(normalize_config_path(path));
+        let processed = preprocess_includes(&content, base_dir, 0, &mut source_files)?;
 
         let parsed_toml: toml::Value =
             toml::from_str(&processed).map_err(|e| ProxyError::Config(e.to_string()))?;
@@ -285,6 +328,84 @@ impl ProxyConfig {
             ));
         }
 
+        if config.general.me_writer_cmd_channel_capacity == 0 {
+            return Err(ProxyError::Config(
+                "general.me_writer_cmd_channel_capacity must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_route_channel_capacity == 0 {
+            return Err(ProxyError::Config(
+                "general.me_route_channel_capacity must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_c2me_channel_capacity == 0 {
+            return Err(ProxyError::Config(
+                "general.me_c2me_channel_capacity must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_reader_route_data_wait_ms > 20 {
+            return Err(ProxyError::Config(
+                "general.me_reader_route_data_wait_ms must be within [0, 20]".to_string(),
+            ));
+        }
+
+        if !(1..=512).contains(&config.general.me_d2c_flush_batch_max_frames) {
+            return Err(ProxyError::Config(
+                "general.me_d2c_flush_batch_max_frames must be within [1, 512]".to_string(),
+            ));
+        }
+
+        if !(4096..=2 * 1024 * 1024).contains(&config.general.me_d2c_flush_batch_max_bytes) {
+            return Err(ProxyError::Config(
+                "general.me_d2c_flush_batch_max_bytes must be within [4096, 2097152]".to_string(),
+            ));
+        }
+
+        if config.general.me_d2c_flush_batch_max_delay_us > 5000 {
+            return Err(ProxyError::Config(
+                "general.me_d2c_flush_batch_max_delay_us must be within [0, 5000]".to_string(),
+            ));
+        }
+
+        if !(4096..=1024 * 1024).contains(&config.general.direct_relay_copy_buf_c2s_bytes) {
+            return Err(ProxyError::Config(
+                "general.direct_relay_copy_buf_c2s_bytes must be within [4096, 1048576]".to_string(),
+            ));
+        }
+
+        if !(8192..=2 * 1024 * 1024).contains(&config.general.direct_relay_copy_buf_s2c_bytes) {
+            return Err(ProxyError::Config(
+                "general.direct_relay_copy_buf_s2c_bytes must be within [8192, 2097152]".to_string(),
+            ));
+        }
+
+        if config.general.me_health_interval_ms_unhealthy == 0 {
+            return Err(ProxyError::Config(
+                "general.me_health_interval_ms_unhealthy must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_health_interval_ms_healthy == 0 {
+            return Err(ProxyError::Config(
+                "general.me_health_interval_ms_healthy must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_admission_poll_ms == 0 {
+            return Err(ProxyError::Config(
+                "general.me_admission_poll_ms must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_warn_rate_limit_ms == 0 {
+            return Err(ProxyError::Config(
+                "general.me_warn_rate_limit_ms must be > 0".to_string(),
+            ));
+        }
+
         if config.access.user_max_unique_ips_window_secs == 0 {
             return Err(ProxyError::Config(
                 "access.user_max_unique_ips_window_secs must be > 0".to_string(),
@@ -477,6 +598,12 @@ impl ProxyConfig {
             ));
         }
 
+        if !(2..=4).contains(&config.general.me_writer_pick_sample_size) {
+            return Err(ProxyError::Config(
+                "general.me_writer_pick_sample_size must be within [2, 4]".to_string(),
+            ));
+        }
+
         if config.general.me_route_inline_recovery_attempts == 0 {
             return Err(ProxyError::Config(
                 "general.me_route_inline_recovery_attempts must be > 0".to_string(),
@@ -702,7 +829,11 @@ impl ProxyConfig {
             .entry("203".to_string())
             .or_insert_with(|| vec!["91.105.192.100:443".to_string()]);
 
-        Ok(config)
+        Ok(LoadedConfig {
+            config,
+            source_files: source_files.into_iter().collect(),
+            rendered_hash: hash_rendered_snapshot(&processed),
+        })
     }
 
     pub fn validate(&self) -> Result<()> {
@@ -1027,6 +1158,48 @@ mod tests {
         );
     }
 
+    #[test]
+    fn load_with_metadata_collects_include_files() {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let dir = std::env::temp_dir().join(format!("telemt_load_metadata_{nonce}"));
+        std::fs::create_dir_all(&dir).unwrap();
+        let main_path = dir.join("config.toml");
+        let include_path = dir.join("included.toml");
+
+        std::fs::write(
+            &include_path,
+            r#"
+                [access.users]
+                user = "00000000000000000000000000000000"
+            "#,
+        )
+        .unwrap();
+        std::fs::write(
+            &main_path,
+            r#"
+                include = "included.toml"
+
+                [censorship]
+                tls_domain = "example.com"
+            "#,
+        )
+        .unwrap();
+
+        let loaded = ProxyConfig::load_with_metadata(&main_path).unwrap();
+        let main_normalized = normalize_config_path(&main_path);
+        let include_normalized = normalize_config_path(&include_path);
+
+        assert!(loaded.source_files.contains(&main_normalized));
+        assert!(loaded.source_files.contains(&include_normalized));
+
+        let _ = std::fs::remove_file(main_path);
+        let _ = std::fs::remove_file(include_path);
+        let _ = std::fs::remove_dir(dir);
+    }
+
     #[test]
     fn dc_overrides_inject_dc203_default() {
         let toml = r#"

src/config/types.rs

@@ -3,6 +3,7 @@ use ipnetwork::IpNetwork;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::net::IpAddr;
+use std::path::PathBuf;
 
 use super::defaults::*;
 
@@ -212,6 +213,32 @@ impl MeRouteNoWriterMode {
     }
 }
 
+/// Middle-End writer selection mode for new client bindings.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum MeWriterPickMode {
+    SortedRr,
+    #[default]
+    P2c,
+}
+
+impl MeWriterPickMode {
+    pub fn as_u8(self) -> u8 {
+        match self {
+            MeWriterPickMode::SortedRr => 0,
+            MeWriterPickMode::P2c => 1,
+        }
+    }
+
+    pub fn from_u8(raw: u8) -> Self {
+        match raw {
+            0 => MeWriterPickMode::SortedRr,
+            1 => MeWriterPickMode::P2c,
+            _ => MeWriterPickMode::P2c,
+        }
+    }
+}
+
 /// Per-user unique source IP limit mode.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
 #[serde(rename_all = "snake_case")]
@@ -330,6 +357,9 @@ impl Default for NetworkConfig {
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct GeneralConfig {
+    #[serde(default)]
+    pub data_path: Option<PathBuf>,
+
     #[serde(default)]
     pub modes: ProxyModes,
 
@@ -420,6 +450,48 @@ pub struct GeneralConfig {
     #[serde(default = "default_rpc_proxy_req_every")]
     pub rpc_proxy_req_every: u64,
 
+    /// Capacity of per-ME writer command channel.
+    #[serde(default = "default_me_writer_cmd_channel_capacity")]
+    pub me_writer_cmd_channel_capacity: usize,
+
+    /// Capacity of per-connection ME response route channel.
+    #[serde(default = "default_me_route_channel_capacity")]
+    pub me_route_channel_capacity: usize,
+
+    /// Capacity of per-client command queue from client reader to ME sender task.
+    #[serde(default = "default_me_c2me_channel_capacity")]
+    pub me_c2me_channel_capacity: usize,
+
+    /// Bounded wait in milliseconds for routing ME DATA to per-connection queue.
+    /// `0` keeps legacy no-wait behavior.
+    #[serde(default = "default_me_reader_route_data_wait_ms")]
+    pub me_reader_route_data_wait_ms: u64,
+
+    /// Maximum number of ME->Client responses coalesced before flush.
+    #[serde(default = "default_me_d2c_flush_batch_max_frames")]
+    pub me_d2c_flush_batch_max_frames: usize,
+
+    /// Maximum total payload bytes coalesced before flush.
+    #[serde(default = "default_me_d2c_flush_batch_max_bytes")]
+    pub me_d2c_flush_batch_max_bytes: usize,
+
+    /// Maximum wait in microseconds to coalesce additional ME->Client responses.
+    /// `0` disables timed coalescing.
+    #[serde(default = "default_me_d2c_flush_batch_max_delay_us")]
+    pub me_d2c_flush_batch_max_delay_us: u64,
+
+    /// Flush client writer immediately after quick-ack write.
+    #[serde(default = "default_me_d2c_ack_flush_immediate")]
+    pub me_d2c_ack_flush_immediate: bool,
+
+    /// Copy buffer size for client->DC direction in direct relay.
+    #[serde(default = "default_direct_relay_copy_buf_c2s_bytes")]
+    pub direct_relay_copy_buf_c2s_bytes: usize,
+
+    /// Copy buffer size for DC->client direction in direct relay.
+    #[serde(default = "default_direct_relay_copy_buf_s2c_bytes")]
+    pub direct_relay_copy_buf_s2c_bytes: usize,
+
     /// Max pending ciphertext buffer per client writer (bytes).
     /// Controls FakeTLS backpressure vs throughput.
     #[serde(default = "default_crypto_pending_buffer")]
@@ -620,6 +692,22 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_route_backpressure_high_watermark_pct")]
     pub me_route_backpressure_high_watermark_pct: u8,
 
+    /// Health monitor interval in milliseconds while writer coverage is degraded.
+    #[serde(default = "default_me_health_interval_ms_unhealthy")]
+    pub me_health_interval_ms_unhealthy: u64,
+
+    /// Health monitor interval in milliseconds while writer coverage is stable.
+    #[serde(default = "default_me_health_interval_ms_healthy")]
+    pub me_health_interval_ms_healthy: u64,
+
+    /// Poll interval in milliseconds for conditional-admission state checks.
+    #[serde(default = "default_me_admission_poll_ms")]
+    pub me_admission_poll_ms: u64,
+
+    /// Cooldown for repetitive ME warning logs in milliseconds.
+    #[serde(default = "default_me_warn_rate_limit_ms")]
+    pub me_warn_rate_limit_ms: u64,
+
     /// ME route behavior when no writer is immediately available.
     #[serde(default)]
     pub me_route_no_writer_mode: MeRouteNoWriterMode,
@@ -710,6 +798,11 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_pool_drain_ttl_secs")]
     pub me_pool_drain_ttl_secs: u64,
 
+    /// Maximum allowed number of draining ME writers before oldest ones are force-closed in batches.
+    /// Set to 0 to disable threshold-based draining cleanup and keep timeout-only behavior.
+    #[serde(default = "default_me_pool_drain_threshold")]
+    pub me_pool_drain_threshold: u64,
+
     /// Policy for new binds on stale draining writers.
     #[serde(default)]
     pub me_bind_stale_mode: MeBindStaleMode,
@@ -754,6 +847,14 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_deterministic_writer_sort")]
     pub me_deterministic_writer_sort: bool,
 
+    /// Writer selection mode for ME route bind path.
+    #[serde(default)]
+    pub me_writer_pick_mode: MeWriterPickMode,
+
+    /// Number of candidates sampled by writer picker in `p2c` mode.
+    #[serde(default = "default_me_writer_pick_sample_size")]
+    pub me_writer_pick_sample_size: u8,
+
     /// Enable NTP drift check at startup.
     #[serde(default = "default_ntp_check")]
     pub ntp_check: bool,
@@ -774,6 +875,7 @@ pub struct GeneralConfig {
 impl Default for GeneralConfig {
     fn default() -> Self {
         Self {
+            data_path: None,
             modes: ProxyModes::default(),
             prefer_ipv6: false,
             fast_mode: default_true(),
@@ -796,6 +898,16 @@ impl Default for GeneralConfig {
             me_keepalive_jitter_secs: default_keepalive_jitter(),
             me_keepalive_payload_random: default_true(),
             rpc_proxy_req_every: default_rpc_proxy_req_every(),
+            me_writer_cmd_channel_capacity: default_me_writer_cmd_channel_capacity(),
+            me_route_channel_capacity: default_me_route_channel_capacity(),
+            me_c2me_channel_capacity: default_me_c2me_channel_capacity(),
+            me_reader_route_data_wait_ms: default_me_reader_route_data_wait_ms(),
+            me_d2c_flush_batch_max_frames: default_me_d2c_flush_batch_max_frames(),
+            me_d2c_flush_batch_max_bytes: default_me_d2c_flush_batch_max_bytes(),
+            me_d2c_flush_batch_max_delay_us: default_me_d2c_flush_batch_max_delay_us(),
+            me_d2c_ack_flush_immediate: default_me_d2c_ack_flush_immediate(),
+            direct_relay_copy_buf_c2s_bytes: default_direct_relay_copy_buf_c2s_bytes(),
+            direct_relay_copy_buf_s2c_bytes: default_direct_relay_copy_buf_s2c_bytes(),
             me_warmup_stagger_enabled: default_true(),
             me_warmup_step_delay_ms: default_warmup_step_delay_ms(),
             me_warmup_step_jitter_ms: default_warmup_step_jitter_ms(),
@@ -837,6 +949,10 @@ impl Default for GeneralConfig {
             me_route_backpressure_base_timeout_ms: default_me_route_backpressure_base_timeout_ms(),
             me_route_backpressure_high_timeout_ms: default_me_route_backpressure_high_timeout_ms(),
             me_route_backpressure_high_watermark_pct: default_me_route_backpressure_high_watermark_pct(),
+            me_health_interval_ms_unhealthy: default_me_health_interval_ms_unhealthy(),
+            me_health_interval_ms_healthy: default_me_health_interval_ms_healthy(),
+            me_admission_poll_ms: default_me_admission_poll_ms(),
+            me_warn_rate_limit_ms: default_me_warn_rate_limit_ms(),
             me_route_no_writer_mode: MeRouteNoWriterMode::default(),
             me_route_no_writer_wait_ms: default_me_route_no_writer_wait_ms(),
             me_route_inline_recovery_attempts: default_me_route_inline_recovery_attempts(),
@@ -867,6 +983,7 @@ impl Default for GeneralConfig {
             me_secret_atomic_snapshot: default_me_secret_atomic_snapshot(),
             proxy_secret_len_max: default_proxy_secret_len_max(),
             me_pool_drain_ttl_secs: default_me_pool_drain_ttl_secs(),
+            me_pool_drain_threshold: default_me_pool_drain_threshold(),
             me_bind_stale_mode: MeBindStaleMode::default(),
             me_bind_stale_ttl_secs: default_me_bind_stale_ttl_secs(),
             me_pool_min_fresh_ratio: default_me_pool_min_fresh_ratio(),
@@ -877,6 +994,8 @@ impl Default for GeneralConfig {
             me_reinit_trigger_channel: default_me_reinit_trigger_channel(),
             me_reinit_coalesce_window_ms: default_me_reinit_coalesce_window_ms(),
             me_deterministic_writer_sort: default_me_deterministic_writer_sort(),
+            me_writer_pick_mode: MeWriterPickMode::default(),
+            me_writer_pick_sample_size: default_me_writer_pick_sample_size(),
             ntp_check: default_ntp_check(),
             ntp_servers: default_ntp_servers(),
             auto_degradation_enabled: default_true(),
@@ -936,7 +1055,7 @@ impl Default for LinksConfig {
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct ApiConfig {
     /// Enable or disable REST API.
-    #[serde(default)]
+    #[serde(default = "default_true")]
     pub enabled: bool,
 
     /// Listen address for API in `IP:PORT` format.
@@ -988,7 +1107,7 @@ pub struct ApiConfig {
 impl Default for ApiConfig {
     fn default() -> Self {
         Self {
-            enabled: false,
+            enabled: default_true(),
             listen: default_api_listen(),
             whitelist: default_api_whitelist(),
             auth_header: String::new(),
@@ -1037,9 +1156,17 @@ pub struct ServerConfig {
     #[serde(default = "default_proxy_protocol_header_timeout_ms")]
     pub proxy_protocol_header_timeout_ms: u64,
 
+    /// Port for the Prometheus-compatible metrics endpoint.
+    /// Enables metrics when set; binds on all interfaces (dual-stack) by default.
     #[serde(default)]
     pub metrics_port: Option<u16>,
 
+    /// Listen address for metrics in `IP:PORT` format (e.g. `"127.0.0.1:9090"`).
+    /// When set, takes precedence over `metrics_port` and binds on the specified address only.
+    #[serde(default)]
+    pub metrics_listen: Option<String>,
+
+    /// CIDR whitelist for the metrics endpoint.
     #[serde(default = "default_metrics_whitelist")]
     pub metrics_whitelist: Vec<IpNetwork>,
 
@@ -1048,6 +1175,11 @@ pub struct ServerConfig {
 
     #[serde(default)]
     pub listeners: Vec<ListenerConfig>,
+
+    /// Maximum number of concurrent client connections.
+    /// 0 means unlimited.
+    #[serde(default = "default_server_max_connections")]
+    pub max_connections: u32,
 }
 
 impl Default for ServerConfig {
@@ -1062,9 +1194,11 @@ impl Default for ServerConfig {
             proxy_protocol: false,
             proxy_protocol_header_timeout_ms: default_proxy_protocol_header_timeout_ms(),
             metrics_port: None,
+            metrics_listen: None,
             metrics_whitelist: default_metrics_whitelist(),
             api: ApiConfig::default(),
             listeners: Vec::new(),
+            max_connections: default_server_max_connections(),
         }
     }
 }
@@ -1209,6 +1343,11 @@ pub struct AccessConfig {
     #[serde(default)]
     pub user_max_unique_ips: HashMap<String, usize>,
 
+    /// Global per-user unique IP limit applied when a user has no individual override.
+    /// `0` disables the inherited limit.
+    #[serde(default = "default_user_max_unique_ips_global_each")]
+    pub user_max_unique_ips_global_each: usize,
+
     #[serde(default)]
     pub user_max_unique_ips_mode: UserMaxUniqueIpsMode,
 
@@ -1234,6 +1373,7 @@ impl Default for AccessConfig {
             user_expirations: HashMap::new(),
             user_data_quota: HashMap::new(),
             user_max_unique_ips: HashMap::new(),
+            user_max_unique_ips_global_each: default_user_max_unique_ips_global_each(),
             user_max_unique_ips_mode: UserMaxUniqueIpsMode::default(),
             user_max_unique_ips_window_secs: default_user_max_unique_ips_window_secs(),
             replay_check_len: default_replay_check_len(),

src/ip_tracker.rs

@@ -17,6 +17,7 @@ pub struct UserIpTracker {
     active_ips: Arc<RwLock<HashMap<String, HashMap<IpAddr, usize>>>>,
     recent_ips: Arc<RwLock<HashMap<String, HashMap<IpAddr, Instant>>>>,
     max_ips: Arc<RwLock<HashMap<String, usize>>>,
+    default_max_ips: Arc<RwLock<usize>>,
     limit_mode: Arc<RwLock<UserMaxUniqueIpsMode>>,
     limit_window: Arc<RwLock<Duration>>,
     last_compact_epoch_secs: Arc<AtomicU64>,
@@ -28,6 +29,7 @@ impl UserIpTracker {
             active_ips: Arc::new(RwLock::new(HashMap::new())),
             recent_ips: Arc::new(RwLock::new(HashMap::new())),
             max_ips: Arc::new(RwLock::new(HashMap::new())),
+            default_max_ips: Arc::new(RwLock::new(0)),
             limit_mode: Arc::new(RwLock::new(UserMaxUniqueIpsMode::ActiveWindow)),
             limit_window: Arc::new(RwLock::new(Duration::from_secs(30))),
             last_compact_epoch_secs: Arc::new(AtomicU64::new(0)),
@@ -100,7 +102,10 @@ impl UserIpTracker {
         limits.remove(username);
     }
 
-    pub async fn load_limits(&self, limits: &HashMap<String, usize>) {
+    pub async fn load_limits(&self, default_limit: usize, limits: &HashMap<String, usize>) {
+        let mut default_max_ips = self.default_max_ips.write().await;
+        *default_max_ips = default_limit;
+        drop(default_max_ips);
         let mut max_ips = self.max_ips.write().await;
         max_ips.clone_from(limits);
     }
@@ -114,9 +119,14 @@ impl UserIpTracker {
 
     pub async fn check_and_add(&self, username: &str, ip: IpAddr) -> Result<(), String> {
         self.maybe_compact_empty_users().await;
+        let default_max_ips = *self.default_max_ips.read().await;
         let limit = {
             let max_ips = self.max_ips.read().await;
-            max_ips.get(username).copied()
+            max_ips
+                .get(username)
+                .copied()
+                .filter(|limit| *limit > 0)
+                .or((default_max_ips > 0).then_some(default_max_ips))
         };
         let mode = *self.limit_mode.read().await;
         let window = *self.limit_window.read().await;
@@ -255,10 +265,16 @@ impl UserIpTracker {
     pub async fn get_stats(&self) -> Vec<(String, usize, usize)> {
         let active_ips = self.active_ips.read().await;
         let max_ips = self.max_ips.read().await;
+        let default_max_ips = *self.default_max_ips.read().await;
 
         let mut stats = Vec::new();
         for (username, user_ips) in active_ips.iter() {
-            let limit = max_ips.get(username).copied().unwrap_or(0);
+            let limit = max_ips
+                .get(username)
+                .copied()
+                .filter(|limit| *limit > 0)
+                .or((default_max_ips > 0).then_some(default_max_ips))
+                .unwrap_or(0);
             stats.push((username.clone(), user_ips.len(), limit));
         }
 
@@ -293,8 +309,13 @@ impl UserIpTracker {
     }
 
     pub async fn get_user_limit(&self, username: &str) -> Option<usize> {
+        let default_max_ips = *self.default_max_ips.read().await;
         let max_ips = self.max_ips.read().await;
-        max_ips.get(username).copied()
+        max_ips
+            .get(username)
+            .copied()
+            .filter(|limit| *limit > 0)
+            .or((default_max_ips > 0).then_some(default_max_ips))
     }
 
     pub async fn format_stats(&self) -> String {
@@ -546,7 +567,7 @@ mod tests {
         config_limits.insert("user1".to_string(), 5);
         config_limits.insert("user2".to_string(), 3);
 
-        tracker.load_limits(&config_limits).await;
+        tracker.load_limits(0, &config_limits).await;
 
         assert_eq!(tracker.get_user_limit("user1").await, Some(5));
         assert_eq!(tracker.get_user_limit("user2").await, Some(3));
@@ -560,16 +581,46 @@ mod tests {
         let mut first = HashMap::new();
         first.insert("user1".to_string(), 2);
         first.insert("user2".to_string(), 3);
-        tracker.load_limits(&first).await;
+        tracker.load_limits(0, &first).await;
 
         let mut second = HashMap::new();
         second.insert("user2".to_string(), 5);
-        tracker.load_limits(&second).await;
+        tracker.load_limits(0, &second).await;
 
         assert_eq!(tracker.get_user_limit("user1").await, None);
         assert_eq!(tracker.get_user_limit("user2").await, Some(5));
     }
 
+    #[tokio::test]
+    async fn test_global_each_limit_applies_without_user_override() {
+        let tracker = UserIpTracker::new();
+        tracker.load_limits(2, &HashMap::new()).await;
+
+        let ip1 = test_ipv4(172, 16, 0, 1);
+        let ip2 = test_ipv4(172, 16, 0, 2);
+        let ip3 = test_ipv4(172, 16, 0, 3);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip3).await.is_err());
+        assert_eq!(tracker.get_user_limit("test_user").await, Some(2));
+    }
+
+    #[tokio::test]
+    async fn test_user_override_wins_over_global_each_limit() {
+        let tracker = UserIpTracker::new();
+        let mut limits = HashMap::new();
+        limits.insert("test_user".to_string(), 1);
+        tracker.load_limits(3, &limits).await;
+
+        let ip1 = test_ipv4(172, 17, 0, 1);
+        let ip2 = test_ipv4(172, 17, 0, 2);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+        assert_eq!(tracker.get_user_limit("test_user").await, Some(1));
+    }
+
     #[tokio::test]
     async fn test_time_window_mode_blocks_recent_ip_churn() {
         let tracker = UserIpTracker::new();

src/ip_tracker_regression_tests.rs

@@ -0,0 +1,450 @@
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv4Addr};
+use std::sync::Arc;
+use std::time::Duration;
+
+use crate::config::UserMaxUniqueIpsMode;
+use crate::ip_tracker::UserIpTracker;
+
+fn ip_from_idx(idx: u32) -> IpAddr {
+    let a = 10u8;
+    let b = ((idx / 65_536) % 256) as u8;
+    let c = ((idx / 256) % 256) as u8;
+    let d = (idx % 256) as u8;
+    IpAddr::V4(Ipv4Addr::new(a, b, c, d))
+}
+
+#[tokio::test]
+async fn active_window_enforces_large_unique_ip_burst() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("burst_user", 64).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::ActiveWindow, 30)
+        .await;
+
+    for idx in 0..64 {
+        assert!(tracker.check_and_add("burst_user", ip_from_idx(idx)).await.is_ok());
+    }
+    assert!(tracker.check_and_add("burst_user", ip_from_idx(9_999)).await.is_err());
+    assert_eq!(tracker.get_active_ip_count("burst_user").await, 64);
+}
+
+#[tokio::test]
+async fn global_limit_applies_across_many_users() {
+    let tracker = UserIpTracker::new();
+    tracker.load_limits(3, &HashMap::new()).await;
+
+    for user_idx in 0..150u32 {
+        let user = format!("u{}", user_idx);
+        assert!(tracker.check_and_add(&user, ip_from_idx(user_idx * 10)).await.is_ok());
+        assert!(tracker
+            .check_and_add(&user, ip_from_idx(user_idx * 10 + 1))
+            .await
+            .is_ok());
+        assert!(tracker
+            .check_and_add(&user, ip_from_idx(user_idx * 10 + 2))
+            .await
+            .is_ok());
+        assert!(tracker
+            .check_and_add(&user, ip_from_idx(user_idx * 10 + 3))
+            .await
+            .is_err());
+    }
+
+    assert_eq!(tracker.get_stats().await.len(), 150);
+}
+
+#[tokio::test]
+async fn user_zero_override_falls_back_to_global_limit() {
+    let tracker = UserIpTracker::new();
+    let mut limits = HashMap::new();
+    limits.insert("target".to_string(), 0);
+    tracker.load_limits(2, &limits).await;
+
+    assert!(tracker.check_and_add("target", ip_from_idx(1)).await.is_ok());
+    assert!(tracker.check_and_add("target", ip_from_idx(2)).await.is_ok());
+    assert!(tracker.check_and_add("target", ip_from_idx(3)).await.is_err());
+    assert_eq!(tracker.get_user_limit("target").await, Some(2));
+}
+
+#[tokio::test]
+async fn remove_ip_is_idempotent_after_counter_reaches_zero() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("u", 2).await;
+    let ip = ip_from_idx(42);
+
+    tracker.check_and_add("u", ip).await.unwrap();
+    tracker.remove_ip("u", ip).await;
+    tracker.remove_ip("u", ip).await;
+    tracker.remove_ip("u", ip).await;
+
+    assert_eq!(tracker.get_active_ip_count("u").await, 0);
+    assert!(!tracker.is_ip_active("u", ip).await);
+}
+
+#[tokio::test]
+async fn clear_user_ips_resets_active_and_recent() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("u", 10).await;
+
+    for idx in 0..6 {
+        tracker.check_and_add("u", ip_from_idx(idx)).await.unwrap();
+    }
+
+    tracker.clear_user_ips("u").await;
+
+    assert_eq!(tracker.get_active_ip_count("u").await, 0);
+    let counts = tracker
+        .get_recent_counts_for_users(&["u".to_string()])
+        .await;
+    assert_eq!(counts.get("u").copied().unwrap_or(0), 0);
+}
+
+#[tokio::test]
+async fn clear_all_resets_multi_user_state() {
+    let tracker = UserIpTracker::new();
+
+    for user_idx in 0..80u32 {
+        let user = format!("u{}", user_idx);
+        for ip_idx in 0..3 {
+            tracker
+                .check_and_add(&user, ip_from_idx(user_idx * 100 + ip_idx))
+                .await
+                .unwrap();
+        }
+    }
+
+    tracker.clear_all().await;
+
+    assert!(tracker.get_stats().await.is_empty());
+    let users = (0..80u32)
+        .map(|idx| format!("u{}", idx))
+        .collect::<Vec<_>>();
+    let recent = tracker.get_recent_counts_for_users(&users).await;
+    assert!(recent.values().all(|count| *count == 0));
+}
+
+#[tokio::test]
+async fn get_active_ips_for_users_are_sorted() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("user", 10).await;
+
+    tracker
+        .check_and_add("user", IpAddr::V4(Ipv4Addr::new(10, 0, 0, 9)))
+        .await
+        .unwrap();
+    tracker
+        .check_and_add("user", IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1)))
+        .await
+        .unwrap();
+    tracker
+        .check_and_add("user", IpAddr::V4(Ipv4Addr::new(10, 0, 0, 5)))
+        .await
+        .unwrap();
+
+    let map = tracker
+        .get_active_ips_for_users(&["user".to_string()])
+        .await;
+    let ips = map.get("user").cloned().unwrap_or_default();
+
+    assert_eq!(
+        ips,
+        vec![
+            IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1)),
+            IpAddr::V4(Ipv4Addr::new(10, 0, 0, 5)),
+            IpAddr::V4(Ipv4Addr::new(10, 0, 0, 9)),
+        ]
+    );
+}
+
+#[tokio::test]
+async fn get_recent_ips_for_users_are_sorted() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("user", 10).await;
+
+    tracker
+        .check_and_add("user", IpAddr::V4(Ipv4Addr::new(10, 1, 0, 9)))
+        .await
+        .unwrap();
+    tracker
+        .check_and_add("user", IpAddr::V4(Ipv4Addr::new(10, 1, 0, 1)))
+        .await
+        .unwrap();
+    tracker
+        .check_and_add("user", IpAddr::V4(Ipv4Addr::new(10, 1, 0, 5)))
+        .await
+        .unwrap();
+
+    let map = tracker
+        .get_recent_ips_for_users(&["user".to_string()])
+        .await;
+    let ips = map.get("user").cloned().unwrap_or_default();
+
+    assert_eq!(
+        ips,
+        vec![
+            IpAddr::V4(Ipv4Addr::new(10, 1, 0, 1)),
+            IpAddr::V4(Ipv4Addr::new(10, 1, 0, 5)),
+            IpAddr::V4(Ipv4Addr::new(10, 1, 0, 9)),
+        ]
+    );
+}
+
+#[tokio::test]
+async fn time_window_expires_for_large_rotation() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("tw", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 1)
+        .await;
+
+    tracker.check_and_add("tw", ip_from_idx(1)).await.unwrap();
+    tracker.remove_ip("tw", ip_from_idx(1)).await;
+    assert!(tracker.check_and_add("tw", ip_from_idx(2)).await.is_err());
+
+    tokio::time::sleep(Duration::from_millis(1_100)).await;
+    assert!(tracker.check_and_add("tw", ip_from_idx(2)).await.is_ok());
+}
+
+#[tokio::test]
+async fn combined_mode_blocks_recent_after_disconnect() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("cmb", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::Combined, 2)
+        .await;
+
+    tracker.check_and_add("cmb", ip_from_idx(11)).await.unwrap();
+    tracker.remove_ip("cmb", ip_from_idx(11)).await;
+
+    assert!(tracker.check_and_add("cmb", ip_from_idx(12)).await.is_err());
+}
+
+#[tokio::test]
+async fn load_limits_replaces_large_limit_map() {
+    let tracker = UserIpTracker::new();
+    let mut first = HashMap::new();
+    let mut second = HashMap::new();
+
+    for idx in 0..300usize {
+        first.insert(format!("u{}", idx), 2usize);
+    }
+    for idx in 150..450usize {
+        second.insert(format!("u{}", idx), 4usize);
+    }
+
+    tracker.load_limits(0, &first).await;
+    tracker.load_limits(0, &second).await;
+
+    assert_eq!(tracker.get_user_limit("u20").await, None);
+    assert_eq!(tracker.get_user_limit("u200").await, Some(4));
+    assert_eq!(tracker.get_user_limit("u420").await, Some(4));
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn concurrent_same_user_unique_ip_pressure_stays_bounded() {
+    let tracker = Arc::new(UserIpTracker::new());
+    tracker.set_user_limit("hot", 32).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::ActiveWindow, 30)
+        .await;
+
+    let mut handles = Vec::new();
+    for worker in 0..16u32 {
+        let tracker_cloned = tracker.clone();
+        handles.push(tokio::spawn(async move {
+            let base = worker * 200;
+            for step in 0..200u32 {
+                let _ = tracker_cloned
+                    .check_and_add("hot", ip_from_idx(base + step))
+                    .await;
+            }
+        }));
+    }
+
+    for handle in handles {
+        handle.await.unwrap();
+    }
+
+    assert!(tracker.get_active_ip_count("hot").await <= 32);
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn concurrent_many_users_isolate_limits() {
+    let tracker = Arc::new(UserIpTracker::new());
+    tracker.load_limits(4, &HashMap::new()).await;
+
+    let mut handles = Vec::new();
+    for user_idx in 0..120u32 {
+        let tracker_cloned = tracker.clone();
+        handles.push(tokio::spawn(async move {
+            let user = format!("u{}", user_idx);
+            for ip_idx in 0..10u32 {
+                let _ = tracker_cloned
+                    .check_and_add(&user, ip_from_idx(user_idx * 1_000 + ip_idx))
+                    .await;
+            }
+        }));
+    }
+
+    for handle in handles {
+        handle.await.unwrap();
+    }
+
+    let stats = tracker.get_stats().await;
+    assert_eq!(stats.len(), 120);
+    assert!(stats.iter().all(|(_, active, limit)| *active <= 4 && *limit == 4));
+}
+
+#[tokio::test]
+async fn same_ip_reconnect_high_frequency_keeps_single_unique() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("same", 2).await;
+    let ip = ip_from_idx(9);
+
+    for _ in 0..2_000 {
+        tracker.check_and_add("same", ip).await.unwrap();
+    }
+
+    assert_eq!(tracker.get_active_ip_count("same").await, 1);
+    assert!(tracker.is_ip_active("same", ip).await);
+}
+
+#[tokio::test]
+async fn format_stats_contains_expected_limited_and_unlimited_markers() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("limited", 2).await;
+    tracker.check_and_add("limited", ip_from_idx(1)).await.unwrap();
+    tracker.check_and_add("open", ip_from_idx(2)).await.unwrap();
+
+    let text = tracker.format_stats().await;
+
+    assert!(text.contains("limited"));
+    assert!(text.contains("open"));
+    assert!(text.contains("unlimited"));
+}
+
+#[tokio::test]
+async fn stats_report_global_default_for_users_without_override() {
+    let tracker = UserIpTracker::new();
+    tracker.load_limits(5, &HashMap::new()).await;
+
+    tracker.check_and_add("a", ip_from_idx(1)).await.unwrap();
+    tracker.check_and_add("b", ip_from_idx(2)).await.unwrap();
+
+    let stats = tracker.get_stats().await;
+    assert!(stats.iter().any(|(user, _, limit)| user == "a" && *limit == 5));
+    assert!(stats.iter().any(|(user, _, limit)| user == "b" && *limit == 5));
+}
+
+#[tokio::test]
+async fn stress_cycle_add_remove_clear_preserves_empty_end_state() {
+    let tracker = UserIpTracker::new();
+
+    for cycle in 0..50u32 {
+        let user = format!("cycle{}", cycle);
+        tracker.set_user_limit(&user, 128).await;
+
+        for ip_idx in 0..128u32 {
+            tracker
+                .check_and_add(&user, ip_from_idx(cycle * 10_000 + ip_idx))
+                .await
+                .unwrap();
+        }
+
+        for ip_idx in 0..128u32 {
+            tracker
+                .remove_ip(&user, ip_from_idx(cycle * 10_000 + ip_idx))
+                .await;
+        }
+
+        tracker.clear_user_ips(&user).await;
+    }
+
+    assert!(tracker.get_stats().await.is_empty());
+}
+
+#[tokio::test]
+async fn remove_unknown_user_or_ip_does_not_corrupt_state() {
+    let tracker = UserIpTracker::new();
+
+    tracker.remove_ip("no_user", ip_from_idx(1)).await;
+    tracker.check_and_add("x", ip_from_idx(2)).await.unwrap();
+    tracker.remove_ip("x", ip_from_idx(3)).await;
+
+    assert_eq!(tracker.get_active_ip_count("x").await, 1);
+    assert!(tracker.is_ip_active("x", ip_from_idx(2)).await);
+}
+
+#[tokio::test]
+async fn active_and_recent_views_match_after_mixed_workload() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("mix", 16).await;
+
+    for ip_idx in 0..12u32 {
+        tracker.check_and_add("mix", ip_from_idx(ip_idx)).await.unwrap();
+    }
+    for ip_idx in 0..6u32 {
+        tracker.remove_ip("mix", ip_from_idx(ip_idx)).await;
+    }
+
+    let active = tracker
+        .get_active_ips_for_users(&["mix".to_string()])
+        .await
+        .get("mix")
+        .cloned()
+        .unwrap_or_default();
+    let recent_count = tracker
+        .get_recent_counts_for_users(&["mix".to_string()])
+        .await
+        .get("mix")
+        .copied()
+        .unwrap_or(0);
+
+    assert_eq!(active.len(), 6);
+    assert!(recent_count >= active.len());
+    assert!(recent_count <= 12);
+}
+
+#[tokio::test]
+async fn global_limit_switch_updates_enforcement_immediately() {
+    let tracker = UserIpTracker::new();
+    tracker.load_limits(2, &HashMap::new()).await;
+
+    assert!(tracker.check_and_add("u", ip_from_idx(1)).await.is_ok());
+    assert!(tracker.check_and_add("u", ip_from_idx(2)).await.is_ok());
+    assert!(tracker.check_and_add("u", ip_from_idx(3)).await.is_err());
+
+    tracker.clear_user_ips("u").await;
+    tracker.load_limits(4, &HashMap::new()).await;
+
+    assert!(tracker.check_and_add("u", ip_from_idx(1)).await.is_ok());
+    assert!(tracker.check_and_add("u", ip_from_idx(2)).await.is_ok());
+    assert!(tracker.check_and_add("u", ip_from_idx(3)).await.is_ok());
+    assert!(tracker.check_and_add("u", ip_from_idx(4)).await.is_ok());
+    assert!(tracker.check_and_add("u", ip_from_idx(5)).await.is_err());
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn concurrent_reconnect_and_disconnect_preserves_non_negative_counts() {
+    let tracker = Arc::new(UserIpTracker::new());
+    tracker.set_user_limit("cc", 8).await;
+
+    let mut handles = Vec::new();
+    for worker in 0..8u32 {
+        let tracker_cloned = tracker.clone();
+        handles.push(tokio::spawn(async move {
+            let ip = ip_from_idx(50 + worker);
+            for _ in 0..500u32 {
+                let _ = tracker_cloned.check_and_add("cc", ip).await;
+                tracker_cloned.remove_ip("cc", ip).await;
+            }
+        }));
+    }
+
+    for handle in handles {
+        handle.await.unwrap();
+    }
+
+    assert!(tracker.get_active_ip_count("cc").await <= 8);
+}

src/maestro/admission.rs

@@ -0,0 +1,130 @@
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use tokio::sync::watch;
+use tracing::{info, warn};
+
+use crate::config::ProxyConfig;
+use crate::proxy::route_mode::{RelayRouteMode, RouteRuntimeController};
+use crate::transport::middle_proxy::MePool;
+
+const STARTUP_FALLBACK_AFTER: Duration = Duration::from_secs(80);
+const RUNTIME_FALLBACK_AFTER: Duration = Duration::from_secs(6);
+
+pub(crate) async fn configure_admission_gate(
+    config: &Arc<ProxyConfig>,
+    me_pool: Option<Arc<MePool>>,
+    route_runtime: Arc<RouteRuntimeController>,
+    admission_tx: &watch::Sender<bool>,
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+) {
+    if config.general.use_middle_proxy {
+        if let Some(pool) = me_pool.as_ref() {
+            let initial_ready = pool.admission_ready_conditional_cast().await;
+            admission_tx.send_replace(initial_ready);
+            let _ = route_runtime.set_mode(RelayRouteMode::Middle);
+            if initial_ready {
+                info!("Conditional-admission gate: open / ME pool READY");
+            } else {
+                warn!("Conditional-admission gate: closed / ME pool is NOT ready)");
+            }
+
+            let pool_for_gate = pool.clone();
+            let admission_tx_gate = admission_tx.clone();
+            let route_runtime_gate = route_runtime.clone();
+            let mut config_rx_gate = config_rx.clone();
+            let mut admission_poll_ms = config.general.me_admission_poll_ms.max(1);
+            let mut fallback_enabled = config.general.me2dc_fallback;
+            tokio::spawn(async move {
+                let mut gate_open = initial_ready;
+                let mut route_mode = RelayRouteMode::Middle;
+                let mut ready_observed = initial_ready;
+                let mut not_ready_since = if initial_ready {
+                    None
+                } else {
+                    Some(Instant::now())
+                };
+                loop {
+                    tokio::select! {
+                        changed = config_rx_gate.changed() => {
+                            if changed.is_err() {
+                                break;
+                            }
+                            let cfg = config_rx_gate.borrow_and_update().clone();
+                            admission_poll_ms = cfg.general.me_admission_poll_ms.max(1);
+                            fallback_enabled = cfg.general.me2dc_fallback;
+                            continue;
+                        }
+                        _ = tokio::time::sleep(Duration::from_millis(admission_poll_ms)) => {}
+                    }
+                    let ready = pool_for_gate.admission_ready_conditional_cast().await;
+                    let now = Instant::now();
+                    let (next_gate_open, next_route_mode, next_fallback_active) = if ready {
+                        ready_observed = true;
+                        not_ready_since = None;
+                        (true, RelayRouteMode::Middle, false)
+                    } else {
+                        let not_ready_started_at = *not_ready_since.get_or_insert(now);
+                        let not_ready_for = now.saturating_duration_since(not_ready_started_at);
+                        let fallback_after = if ready_observed {
+                            RUNTIME_FALLBACK_AFTER
+                        } else {
+                            STARTUP_FALLBACK_AFTER
+                        };
+                        if fallback_enabled && not_ready_for > fallback_after {
+                            (true, RelayRouteMode::Direct, true)
+                        } else {
+                            (false, RelayRouteMode::Middle, false)
+                        }
+                    };
+
+                    if next_route_mode != route_mode {
+                        route_mode = next_route_mode;
+                        if let Some(snapshot) = route_runtime_gate.set_mode(route_mode) {
+                            if matches!(route_mode, RelayRouteMode::Middle) {
+                                info!(
+                                    target_mode = route_mode.as_str(),
+                                    cutover_generation = snapshot.generation,
+                                    "Middle-End routing restored for new sessions"
+                                );
+                            } else {
+                                let fallback_after = if ready_observed {
+                                    RUNTIME_FALLBACK_AFTER
+                                } else {
+                                    STARTUP_FALLBACK_AFTER
+                                };
+                                warn!(
+                                    target_mode = route_mode.as_str(),
+                                    cutover_generation = snapshot.generation,
+                                    grace_secs = fallback_after.as_secs(),
+                                    "ME pool stayed not-ready beyond grace; routing new sessions via Direct-DC"
+                                );
+                            }
+                        }
+                    }
+
+                    if next_gate_open != gate_open {
+                        gate_open = next_gate_open;
+                        admission_tx_gate.send_replace(gate_open);
+                        if gate_open {
+                            if next_fallback_active {
+                                warn!("Conditional-admission gate opened in ME fallback mode");
+                            } else {
+                                info!("Conditional-admission gate opened / ME pool READY");
+                            }
+                        } else {
+                            warn!("Conditional-admission gate closed / ME pool is NOT ready");
+                        }
+                    }
+                }
+            });
+        } else {
+            admission_tx.send_replace(false);
+            let _ = route_runtime.set_mode(RelayRouteMode::Direct);
+            warn!("Conditional-admission gate: closed / ME pool is UNAVAILABLE");
+        }
+    } else {
+        admission_tx.send_replace(true);
+        let _ = route_runtime.set_mode(RelayRouteMode::Direct);
+    }
+}

src/maestro/connectivity.rs

@@ -0,0 +1,220 @@
+use std::sync::Arc;
+use std::time::Instant;
+
+use tokio::sync::RwLock;
+use tracing::info;
+
+use crate::config::ProxyConfig;
+use crate::crypto::SecureRandom;
+use crate::network::probe::NetworkDecision;
+use crate::startup::{
+    COMPONENT_DC_CONNECTIVITY_PING, COMPONENT_ME_CONNECTIVITY_PING, COMPONENT_RUNTIME_READY,
+    StartupTracker,
+};
+use crate::transport::middle_proxy::{
+    MePingFamily, MePingSample, MePool, format_me_route, format_sample_line, run_me_ping,
+};
+use crate::transport::UpstreamManager;
+
+pub(crate) async fn run_startup_connectivity(
+    config: &Arc<ProxyConfig>,
+    me_pool: &Option<Arc<MePool>>,
+    rng: Arc<SecureRandom>,
+    startup_tracker: &Arc<StartupTracker>,
+    upstream_manager: Arc<UpstreamManager>,
+    prefer_ipv6: bool,
+    decision: &NetworkDecision,
+    process_started_at: Instant,
+    api_me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
+) {
+    if me_pool.is_some() {
+        startup_tracker
+            .start_component(
+                COMPONENT_ME_CONNECTIVITY_PING,
+                Some("run startup ME connectivity check".to_string()),
+            )
+            .await;
+    } else {
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_CONNECTIVITY_PING,
+                Some("ME pool is not available".to_string()),
+            )
+            .await;
+    }
+    if let Some(pool) = me_pool {
+        let me_results = run_me_ping(pool, &rng).await;
+
+        let v4_ok = me_results.iter().any(|r| {
+            matches!(r.family, MePingFamily::V4)
+                && r.samples.iter().any(|s| s.error.is_none() && s.handshake_ms.is_some())
+        });
+        let v6_ok = me_results.iter().any(|r| {
+            matches!(r.family, MePingFamily::V6)
+                && r.samples.iter().any(|s| s.error.is_none() && s.handshake_ms.is_some())
+        });
+
+        info!("================= Telegram ME Connectivity =================");
+        if v4_ok && v6_ok {
+            info!("  IPv4 and IPv6 available");
+        } else if v4_ok {
+            info!("  IPv4 only / IPv6 unavailable");
+        } else if v6_ok {
+            info!("  IPv6 only / IPv4 unavailable");
+        } else {
+            info!("  No ME connectivity");
+        }
+        let me_route =
+            format_me_route(&config.upstreams, &me_results, prefer_ipv6, v4_ok, v6_ok).await;
+        info!("  via {}", me_route);
+        info!("============================================================");
+
+        use std::collections::BTreeMap;
+        let mut grouped: BTreeMap<i32, Vec<MePingSample>> = BTreeMap::new();
+        for report in me_results {
+            for s in report.samples {
+                grouped.entry(s.dc).or_default().push(s);
+            }
+        }
+
+        let family_order = if prefer_ipv6 {
+            vec![MePingFamily::V6, MePingFamily::V4]
+        } else {
+            vec![MePingFamily::V4, MePingFamily::V6]
+        };
+
+        for (dc, samples) in grouped {
+            for family in &family_order {
+                let fam_samples: Vec<&MePingSample> = samples
+                    .iter()
+                    .filter(|s| matches!(s.family, f if &f == family))
+                    .collect();
+                if fam_samples.is_empty() {
+                    continue;
+                }
+
+                let fam_label = match family {
+                    MePingFamily::V4 => "IPv4",
+                    MePingFamily::V6 => "IPv6",
+                };
+                info!("    DC{} [{}]", dc, fam_label);
+                for sample in fam_samples {
+                    let line = format_sample_line(sample);
+                    info!("{}", line);
+                }
+            }
+        }
+        info!("============================================================");
+        startup_tracker
+            .complete_component(
+                COMPONENT_ME_CONNECTIVITY_PING,
+                Some("startup ME connectivity check completed".to_string()),
+            )
+            .await;
+    }
+
+    info!("================= Telegram DC Connectivity =================");
+    startup_tracker
+        .start_component(
+            COMPONENT_DC_CONNECTIVITY_PING,
+            Some("run startup DC connectivity check".to_string()),
+        )
+        .await;
+
+    let ping_results = upstream_manager
+        .ping_all_dcs(
+            prefer_ipv6,
+            &config.dc_overrides,
+            decision.ipv4_dc,
+            decision.ipv6_dc,
+        )
+        .await;
+
+    for upstream_result in &ping_results {
+        let v6_works = upstream_result.v6_results.iter().any(|r| r.rtt_ms.is_some());
+        let v4_works = upstream_result.v4_results.iter().any(|r| r.rtt_ms.is_some());
+
+        if upstream_result.both_available {
+            if prefer_ipv6 {
+                info!("  IPv6 in use / IPv4 is fallback");
+            } else {
+                info!("  IPv4 in use / IPv6 is fallback");
+            }
+        } else if v6_works && !v4_works {
+            info!("  IPv6 only / IPv4 unavailable");
+        } else if v4_works && !v6_works {
+            info!("  IPv4 only / IPv6 unavailable");
+        } else if !v6_works && !v4_works {
+            info!("  No DC connectivity");
+        }
+
+        info!("  via {}", upstream_result.upstream_name);
+        info!("============================================================");
+
+        if v6_works {
+            for dc in &upstream_result.v6_results {
+                let addr_str = format!("{}:{}", dc.dc_addr.ip(), dc.dc_addr.port());
+                match &dc.rtt_ms {
+                    Some(rtt) => {
+                        info!("    DC{} [IPv6] {} - {:.0} ms", dc.dc_idx, addr_str, rtt);
+                    }
+                    None => {
+                        let err = dc.error.as_deref().unwrap_or("fail");
+                        info!("    DC{} [IPv6] {} - FAIL ({})", dc.dc_idx, addr_str, err);
+                    }
+                }
+            }
+
+            info!("============================================================");
+        }
+
+        if v4_works {
+            for dc in &upstream_result.v4_results {
+                let addr_str = format!("{}:{}", dc.dc_addr.ip(), dc.dc_addr.port());
+                match &dc.rtt_ms {
+                    Some(rtt) => {
+                        info!(
+                            "    DC{} [IPv4] {}\t\t\t\t{:.0} ms",
+                            dc.dc_idx, addr_str, rtt
+                        );
+                    }
+                    None => {
+                        let err = dc.error.as_deref().unwrap_or("fail");
+                        info!(
+                            "    DC{} [IPv4] {}:\t\t\t\tFAIL ({})",
+                            dc.dc_idx, addr_str, err
+                        );
+                    }
+                }
+            }
+
+            info!("============================================================");
+        }
+    }
+    startup_tracker
+        .complete_component(
+            COMPONENT_DC_CONNECTIVITY_PING,
+            Some("startup DC connectivity check completed".to_string()),
+        )
+        .await;
+
+    let initialized_secs = process_started_at.elapsed().as_secs();
+    let second_suffix = if initialized_secs == 1 { "" } else { "s" };
+    startup_tracker
+        .start_component(
+            COMPONENT_RUNTIME_READY,
+            Some("finalize startup runtime state".to_string()),
+        )
+        .await;
+    info!("===================== Telegram Startup =====================");
+    info!(
+        "  DC/ME Initialized in {} second{}",
+        initialized_secs, second_suffix
+    );
+    info!("============================================================");
+
+    if let Some(pool) = me_pool {
+        pool.set_runtime_ready(true);
+    }
+    *api_me_pool.write().await = me_pool.clone();
+}

src/maestro/helpers.rs

@@ -0,0 +1,335 @@
+use std::time::Duration;
+use std::path::PathBuf;
+
+use tokio::sync::watch;
+use tracing::{debug, error, info, warn};
+
+use crate::cli;
+use crate::config::ProxyConfig;
+use crate::transport::middle_proxy::{
+    ProxyConfigData, fetch_proxy_config_with_raw, load_proxy_config_cache, save_proxy_config_cache,
+};
+
+pub(crate) fn parse_cli() -> (String, Option<PathBuf>, bool, Option<String>) {
+    let mut config_path = "config.toml".to_string();
+    let mut data_path: Option<PathBuf> = None;
+    let mut silent = false;
+    let mut log_level: Option<String> = None;
+
+    let args: Vec<String> = std::env::args().skip(1).collect();
+
+    // Check for --init first (handled before tokio)
+    if let Some(init_opts) = cli::parse_init_args(&args) {
+        if let Err(e) = cli::run_init(init_opts) {
+            eprintln!("[telemt] Init failed: {}", e);
+            std::process::exit(1);
+        }
+        std::process::exit(0);
+    }
+
+    let mut i = 0;
+    while i < args.len() {
+        match args[i].as_str() {
+            "--data-path" => {
+                i += 1;
+                if i < args.len() {
+                    data_path = Some(PathBuf::from(args[i].clone()));
+                } else {
+                    eprintln!("Missing value for --data-path");
+                    std::process::exit(0);
+                }
+            }
+            s if s.starts_with("--data-path=") => {
+                data_path = Some(PathBuf::from(s.trim_start_matches("--data-path=").to_string()));
+            }
+            "--silent" | "-s" => {
+                silent = true;
+            }
+            "--log-level" => {
+                i += 1;
+                if i < args.len() {
+                    log_level = Some(args[i].clone());
+                }
+            }
+            s if s.starts_with("--log-level=") => {
+                log_level = Some(s.trim_start_matches("--log-level=").to_string());
+            }
+            "--help" | "-h" => {
+                eprintln!("Usage: telemt [config.toml] [OPTIONS]");
+                eprintln!();
+                eprintln!("Options:");
+                eprintln!("  --data-path <DIR>       Set data directory (absolute path; overrides config value)");
+                eprintln!("  --silent, -s            Suppress info logs");
+                eprintln!("  --log-level <LEVEL>     debug|verbose|normal|silent");
+                eprintln!("  --help, -h              Show this help");
+                eprintln!();
+                eprintln!("Setup (fire-and-forget):");
+                eprintln!(
+                    "  --init                  Generate config, install systemd service, start"
+                );
+                eprintln!("    --port <PORT>          Listen port (default: 443)");
+                eprintln!(
+                    "    --domain <DOMAIN>      TLS domain for masking (default: www.google.com)"
+                );
+                eprintln!(
+                    "    --secret <HEX>         32-char hex secret (auto-generated if omitted)"
+                );
+                eprintln!("    --user <NAME>          Username (default: user)");
+                eprintln!("    --config-dir <DIR>     Config directory (default: /etc/telemt)");
+                eprintln!("    --no-start             Don't start the service after install");
+                std::process::exit(0);
+            }
+            "--version" | "-V" => {
+                println!("telemt {}", env!("CARGO_PKG_VERSION"));
+                std::process::exit(0);
+            }
+            s if !s.starts_with('-') => {
+                config_path = s.to_string();
+            }
+            other => {
+                eprintln!("Unknown option: {}", other);
+            }
+        }
+        i += 1;
+    }
+
+    (config_path, data_path, silent, log_level)
+}
+
+pub(crate) fn print_proxy_links(host: &str, port: u16, config: &ProxyConfig) {
+    info!(target: "telemt::links", "--- Proxy Links ({}) ---", host);
+    for user_name in config.general.links.show.resolve_users(&config.access.users) {
+        if let Some(secret) = config.access.users.get(user_name) {
+            info!(target: "telemt::links", "User: {}", user_name);
+            if config.general.modes.classic {
+                info!(
+                    target: "telemt::links",
+                    "  Classic: tg://proxy?server={}&port={}&secret={}",
+                    host, port, secret
+                );
+            }
+            if config.general.modes.secure {
+                info!(
+                    target: "telemt::links",
+                    "  DD:      tg://proxy?server={}&port={}&secret=dd{}",
+                    host, port, secret
+                );
+            }
+            if config.general.modes.tls {
+                let mut domains = Vec::with_capacity(1 + config.censorship.tls_domains.len());
+                domains.push(config.censorship.tls_domain.clone());
+                for d in &config.censorship.tls_domains {
+                    if !domains.contains(d) {
+                        domains.push(d.clone());
+                    }
+                }
+
+                for domain in domains {
+                    let domain_hex = hex::encode(&domain);
+                    info!(
+                        target: "telemt::links",
+                        "  EE-TLS:  tg://proxy?server={}&port={}&secret=ee{}{}",
+                        host, port, secret, domain_hex
+                    );
+                }
+            }
+        } else {
+            warn!(target: "telemt::links", "User '{}' in show_link not found", user_name);
+        }
+    }
+    info!(target: "telemt::links", "------------------------");
+}
+
+pub(crate) async fn write_beobachten_snapshot(path: &str, payload: &str) -> std::io::Result<()> {
+    if let Some(parent) = std::path::Path::new(path).parent()
+        && !parent.as_os_str().is_empty()
+    {
+        tokio::fs::create_dir_all(parent).await?;
+    }
+    tokio::fs::write(path, payload).await
+}
+
+pub(crate) fn unit_label(value: u64, singular: &'static str, plural: &'static str) -> &'static str {
+    if value == 1 { singular } else { plural }
+}
+
+pub(crate) fn format_uptime(total_secs: u64) -> String {
+    const SECS_PER_MINUTE: u64 = 60;
+    const SECS_PER_HOUR: u64 = 60 * SECS_PER_MINUTE;
+    const SECS_PER_DAY: u64 = 24 * SECS_PER_HOUR;
+    const SECS_PER_MONTH: u64 = 30 * SECS_PER_DAY;
+    const SECS_PER_YEAR: u64 = 12 * SECS_PER_MONTH;
+
+    let mut remaining = total_secs;
+    let years = remaining / SECS_PER_YEAR;
+    remaining %= SECS_PER_YEAR;
+    let months = remaining / SECS_PER_MONTH;
+    remaining %= SECS_PER_MONTH;
+    let days = remaining / SECS_PER_DAY;
+    remaining %= SECS_PER_DAY;
+    let hours = remaining / SECS_PER_HOUR;
+    remaining %= SECS_PER_HOUR;
+    let minutes = remaining / SECS_PER_MINUTE;
+    let seconds = remaining % SECS_PER_MINUTE;
+
+    let mut parts = Vec::new();
+    if total_secs > SECS_PER_YEAR {
+        parts.push(format!("{} {}", years, unit_label(years, "year", "years")));
+    }
+    if total_secs > SECS_PER_MONTH {
+        parts.push(format!(
+            "{} {}",
+            months,
+            unit_label(months, "month", "months")
+        ));
+    }
+    if total_secs > SECS_PER_DAY {
+        parts.push(format!("{} {}", days, unit_label(days, "day", "days")));
+    }
+    if total_secs > SECS_PER_HOUR {
+        parts.push(format!("{} {}", hours, unit_label(hours, "hour", "hours")));
+    }
+    if total_secs > SECS_PER_MINUTE {
+        parts.push(format!(
+            "{} {}",
+            minutes,
+            unit_label(minutes, "minute", "minutes")
+        ));
+    }
+    parts.push(format!(
+        "{} {}",
+        seconds,
+        unit_label(seconds, "second", "seconds")
+    ));
+
+    format!("{} / {} seconds", parts.join(", "), total_secs)
+}
+
+pub(crate) async fn wait_until_admission_open(admission_rx: &mut watch::Receiver<bool>) -> bool {
+    loop {
+        if *admission_rx.borrow() {
+            return true;
+        }
+        if admission_rx.changed().await.is_err() {
+            return *admission_rx.borrow();
+        }
+    }
+}
+
+pub(crate) fn is_expected_handshake_eof(err: &crate::error::ProxyError) -> bool {
+    err.to_string().contains("expected 64 bytes, got 0")
+}
+
+pub(crate) async fn load_startup_proxy_config_snapshot(
+    url: &str,
+    cache_path: Option<&str>,
+    me2dc_fallback: bool,
+    label: &'static str,
+) -> Option<ProxyConfigData> {
+    loop {
+        match fetch_proxy_config_with_raw(url).await {
+            Ok((cfg, raw)) => {
+                if !cfg.map.is_empty() {
+                    if let Some(path) = cache_path
+                        && let Err(e) = save_proxy_config_cache(path, &raw).await
+                    {
+                        warn!(error = %e, path, snapshot = label, "Failed to store startup proxy-config cache");
+                    }
+                    return Some(cfg);
+                }
+
+                warn!(snapshot = label, url, "Startup proxy-config is empty; trying disk cache");
+                if let Some(path) = cache_path {
+                    match load_proxy_config_cache(path).await {
+                        Ok(cached) if !cached.map.is_empty() => {
+                            info!(
+                                snapshot = label,
+                                path,
+                                proxy_for_lines = cached.proxy_for_lines,
+                                "Loaded startup proxy-config from disk cache"
+                            );
+                            return Some(cached);
+                        }
+                        Ok(_) => {
+                            warn!(
+                                snapshot = label,
+                                path,
+                                "Startup proxy-config cache is empty; ignoring cache file"
+                            );
+                        }
+                        Err(cache_err) => {
+                            debug!(
+                                snapshot = label,
+                                path,
+                                error = %cache_err,
+                                "Startup proxy-config cache unavailable"
+                            );
+                        }
+                    }
+                }
+
+                if me2dc_fallback {
+                    error!(
+                        snapshot = label,
+                        "Startup proxy-config unavailable and no saved config found; falling back to direct mode"
+                    );
+                    return None;
+                }
+
+                warn!(
+                    snapshot = label,
+                    retry_in_secs = 2,
+                    "Startup proxy-config unavailable and no saved config found; retrying because me2dc_fallback=false"
+                );
+                tokio::time::sleep(Duration::from_secs(2)).await;
+            }
+            Err(fetch_err) => {
+                if let Some(path) = cache_path {
+                    match load_proxy_config_cache(path).await {
+                        Ok(cached) if !cached.map.is_empty() => {
+                            info!(
+                                snapshot = label,
+                                path,
+                                proxy_for_lines = cached.proxy_for_lines,
+                                "Loaded startup proxy-config from disk cache"
+                            );
+                            return Some(cached);
+                        }
+                        Ok(_) => {
+                            warn!(
+                                snapshot = label,
+                                path,
+                                "Startup proxy-config cache is empty; ignoring cache file"
+                            );
+                        }
+                        Err(cache_err) => {
+                            debug!(
+                                snapshot = label,
+                                path,
+                                error = %cache_err,
+                                "Startup proxy-config cache unavailable"
+                            );
+                        }
+                    }
+                }
+
+                if me2dc_fallback {
+                    error!(
+                        snapshot = label,
+                        error = %fetch_err,
+                        "Startup proxy-config unavailable and no cached data; falling back to direct mode"
+                    );
+                    return None;
+                }
+
+                warn!(
+                    snapshot = label,
+                    error = %fetch_err,
+                    retry_in_secs = 2,
+                    "Startup proxy-config unavailable; retrying because me2dc_fallback=false"
+                );
+                tokio::time::sleep(Duration::from_secs(2)).await;
+            }
+        }
+    }
+}

src/maestro/listeners.rs

@@ -0,0 +1,465 @@
+use std::error::Error;
+use std::net::{IpAddr, SocketAddr};
+use std::sync::Arc;
+use std::time::Duration;
+
+use tokio::net::TcpListener;
+#[cfg(unix)]
+use tokio::net::UnixListener;
+use tokio::sync::{Semaphore, watch};
+use tracing::{debug, error, info, warn};
+
+use crate::config::ProxyConfig;
+use crate::crypto::SecureRandom;
+use crate::ip_tracker::UserIpTracker;
+use crate::proxy::route_mode::{ROUTE_SWITCH_ERROR_MSG, RouteRuntimeController};
+use crate::proxy::ClientHandler;
+use crate::startup::{COMPONENT_LISTENERS_BIND, StartupTracker};
+use crate::stats::beobachten::BeobachtenStore;
+use crate::stats::{ReplayChecker, Stats};
+use crate::stream::BufferPool;
+use crate::tls_front::TlsFrontCache;
+use crate::transport::middle_proxy::MePool;
+use crate::transport::{
+    ListenOptions, UpstreamManager, create_listener, find_listener_processes,
+};
+
+use super::helpers::{is_expected_handshake_eof, print_proxy_links, wait_until_admission_open};
+
+pub(crate) struct BoundListeners {
+    pub(crate) listeners: Vec<(TcpListener, bool)>,
+    pub(crate) has_unix_listener: bool,
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn bind_listeners(
+    config: &Arc<ProxyConfig>,
+    decision_ipv4_dc: bool,
+    decision_ipv6_dc: bool,
+    detected_ip_v4: Option<IpAddr>,
+    detected_ip_v6: Option<IpAddr>,
+    startup_tracker: &Arc<StartupTracker>,
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+    admission_rx: watch::Receiver<bool>,
+    stats: Arc<Stats>,
+    upstream_manager: Arc<UpstreamManager>,
+    replay_checker: Arc<ReplayChecker>,
+    buffer_pool: Arc<BufferPool>,
+    rng: Arc<SecureRandom>,
+    me_pool: Option<Arc<MePool>>,
+    route_runtime: Arc<RouteRuntimeController>,
+    tls_cache: Option<Arc<TlsFrontCache>>,
+    ip_tracker: Arc<UserIpTracker>,
+    beobachten: Arc<BeobachtenStore>,
+    max_connections: Arc<Semaphore>,
+) -> Result<BoundListeners, Box<dyn Error>> {
+    startup_tracker
+        .start_component(
+            COMPONENT_LISTENERS_BIND,
+            Some("bind TCP/Unix listeners".to_string()),
+        )
+        .await;
+    let mut listeners = Vec::new();
+
+    for listener_conf in &config.server.listeners {
+        let addr = SocketAddr::new(listener_conf.ip, config.server.port);
+        if addr.is_ipv4() && !decision_ipv4_dc {
+            warn!(%addr, "Skipping IPv4 listener: IPv4 disabled by [network]");
+            continue;
+        }
+        if addr.is_ipv6() && !decision_ipv6_dc {
+            warn!(%addr, "Skipping IPv6 listener: IPv6 disabled by [network]");
+            continue;
+        }
+        let options = ListenOptions {
+            reuse_port: listener_conf.reuse_allow,
+            ipv6_only: listener_conf.ip.is_ipv6(),
+            ..Default::default()
+        };
+
+        match create_listener(addr, &options) {
+            Ok(socket) => {
+                let listener = TcpListener::from_std(socket.into())?;
+                info!("Listening on {}", addr);
+                let listener_proxy_protocol =
+                    listener_conf.proxy_protocol.unwrap_or(config.server.proxy_protocol);
+
+                let public_host = if let Some(ref announce) = listener_conf.announce {
+                    announce.clone()
+                } else if listener_conf.ip.is_unspecified() {
+                    if listener_conf.ip.is_ipv4() {
+                        detected_ip_v4
+                            .map(|ip| ip.to_string())
+                            .unwrap_or_else(|| listener_conf.ip.to_string())
+                    } else {
+                        detected_ip_v6
+                            .map(|ip| ip.to_string())
+                            .unwrap_or_else(|| listener_conf.ip.to_string())
+                    }
+                } else {
+                    listener_conf.ip.to_string()
+                };
+
+                if config.general.links.public_host.is_none() && !config.general.links.show.is_empty() {
+                    let link_port = config.general.links.public_port.unwrap_or(config.server.port);
+                    print_proxy_links(&public_host, link_port, config);
+                }
+
+                listeners.push((listener, listener_proxy_protocol));
+            }
+            Err(e) => {
+                if e.kind() == std::io::ErrorKind::AddrInUse {
+                    let owners = find_listener_processes(addr);
+                    if owners.is_empty() {
+                        error!(
+                            %addr,
+                            "Failed to bind: address already in use (owner process unresolved)"
+                        );
+                    } else {
+                        for owner in owners {
+                            error!(
+                                %addr,
+                                pid = owner.pid,
+                                process = %owner.process,
+                                "Failed to bind: address already in use"
+                            );
+                        }
+                    }
+
+                    if !listener_conf.reuse_allow {
+                        error!(
+                            %addr,
+                            "reuse_allow=false; set [[server.listeners]].reuse_allow=true to allow multi-instance listening"
+                        );
+                    }
+                } else {
+                    error!("Failed to bind to {}: {}", addr, e);
+                }
+            }
+        }
+    }
+
+    if !config.general.links.show.is_empty()
+        && (config.general.links.public_host.is_some() || listeners.is_empty())
+    {
+        let (host, port) = if let Some(ref h) = config.general.links.public_host {
+            (
+                h.clone(),
+                config.general.links.public_port.unwrap_or(config.server.port),
+            )
+        } else {
+            let ip = detected_ip_v4
+                .or(detected_ip_v6)
+                .map(|ip| ip.to_string());
+            if ip.is_none() {
+                warn!(
+                    "show_link is configured but public IP could not be detected. Set public_host in config."
+                );
+            }
+            (
+                ip.unwrap_or_else(|| "UNKNOWN".to_string()),
+                config.general.links.public_port.unwrap_or(config.server.port),
+            )
+        };
+
+        print_proxy_links(&host, port, config);
+    }
+
+    let mut has_unix_listener = false;
+    #[cfg(unix)]
+    if let Some(ref unix_path) = config.server.listen_unix_sock {
+        let _ = tokio::fs::remove_file(unix_path).await;
+
+        let unix_listener = UnixListener::bind(unix_path)?;
+
+        if let Some(ref perm_str) = config.server.listen_unix_sock_perm {
+            match u32::from_str_radix(perm_str.trim_start_matches('0'), 8) {
+                Ok(mode) => {
+                    use std::os::unix::fs::PermissionsExt;
+                    let perms = std::fs::Permissions::from_mode(mode);
+                    if let Err(e) = std::fs::set_permissions(unix_path, perms) {
+                        error!("Failed to set unix socket permissions to {}: {}", perm_str, e);
+                    } else {
+                        info!("Listening on unix:{} (mode {})", unix_path, perm_str);
+                    }
+                }
+                Err(e) => {
+                    warn!("Invalid listen_unix_sock_perm '{}': {}. Ignoring.", perm_str, e);
+                    info!("Listening on unix:{}", unix_path);
+                }
+            }
+        } else {
+            info!("Listening on unix:{}", unix_path);
+        }
+
+        has_unix_listener = true;
+
+        let mut config_rx_unix: watch::Receiver<Arc<ProxyConfig>> = config_rx.clone();
+        let mut admission_rx_unix = admission_rx.clone();
+        let stats = stats.clone();
+        let upstream_manager = upstream_manager.clone();
+        let replay_checker = replay_checker.clone();
+        let buffer_pool = buffer_pool.clone();
+        let rng = rng.clone();
+        let me_pool = me_pool.clone();
+        let route_runtime = route_runtime.clone();
+        let tls_cache = tls_cache.clone();
+        let ip_tracker = ip_tracker.clone();
+        let beobachten = beobachten.clone();
+        let max_connections_unix = max_connections.clone();
+
+        tokio::spawn(async move {
+            let unix_conn_counter = Arc::new(std::sync::atomic::AtomicU64::new(1));
+
+            loop {
+                if !wait_until_admission_open(&mut admission_rx_unix).await {
+                    warn!("Conditional-admission gate channel closed for unix listener");
+                    break;
+                }
+                match unix_listener.accept().await {
+                    Ok((stream, _)) => {
+                        let permit = match max_connections_unix.clone().acquire_owned().await {
+                            Ok(permit) => permit,
+                            Err(_) => {
+                                error!("Connection limiter is closed");
+                                break;
+                            }
+                        };
+                        let conn_id =
+                            unix_conn_counter.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+                        let fake_peer =
+                            SocketAddr::from(([127, 0, 0, 1], (conn_id % 65535) as u16));
+
+                        let config = config_rx_unix.borrow_and_update().clone();
+                        let stats = stats.clone();
+                        let upstream_manager = upstream_manager.clone();
+                        let replay_checker = replay_checker.clone();
+                        let buffer_pool = buffer_pool.clone();
+                        let rng = rng.clone();
+                        let me_pool = me_pool.clone();
+                        let route_runtime = route_runtime.clone();
+                        let tls_cache = tls_cache.clone();
+                        let ip_tracker = ip_tracker.clone();
+                        let beobachten = beobachten.clone();
+                        let proxy_protocol_enabled = config.server.proxy_protocol;
+
+                        tokio::spawn(async move {
+                            let _permit = permit;
+                            if let Err(e) = crate::proxy::client::handle_client_stream(
+                                stream,
+                                fake_peer,
+                                config,
+                                stats,
+                                upstream_manager,
+                                replay_checker,
+                                buffer_pool,
+                                rng,
+                                me_pool,
+                                route_runtime,
+                                tls_cache,
+                                ip_tracker,
+                                beobachten,
+                                proxy_protocol_enabled,
+                            )
+                            .await
+                            {
+                                debug!(error = %e, "Unix socket connection error");
+                            }
+                        });
+                    }
+                    Err(e) => {
+                        error!("Unix socket accept error: {}", e);
+                        tokio::time::sleep(Duration::from_millis(100)).await;
+                    }
+                }
+            }
+        });
+    }
+
+    startup_tracker
+        .complete_component(
+            COMPONENT_LISTENERS_BIND,
+            Some(format!(
+                "listeners configured tcp={} unix={}",
+                listeners.len(),
+                has_unix_listener
+            )),
+        )
+        .await;
+
+    Ok(BoundListeners {
+        listeners,
+        has_unix_listener,
+    })
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn spawn_tcp_accept_loops(
+    listeners: Vec<(TcpListener, bool)>,
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+    admission_rx: watch::Receiver<bool>,
+    stats: Arc<Stats>,
+    upstream_manager: Arc<UpstreamManager>,
+    replay_checker: Arc<ReplayChecker>,
+    buffer_pool: Arc<BufferPool>,
+    rng: Arc<SecureRandom>,
+    me_pool: Option<Arc<MePool>>,
+    route_runtime: Arc<RouteRuntimeController>,
+    tls_cache: Option<Arc<TlsFrontCache>>,
+    ip_tracker: Arc<UserIpTracker>,
+    beobachten: Arc<BeobachtenStore>,
+    max_connections: Arc<Semaphore>,
+) {
+    for (listener, listener_proxy_protocol) in listeners {
+        let mut config_rx: watch::Receiver<Arc<ProxyConfig>> = config_rx.clone();
+        let mut admission_rx_tcp = admission_rx.clone();
+        let stats = stats.clone();
+        let upstream_manager = upstream_manager.clone();
+        let replay_checker = replay_checker.clone();
+        let buffer_pool = buffer_pool.clone();
+        let rng = rng.clone();
+        let me_pool = me_pool.clone();
+        let route_runtime = route_runtime.clone();
+        let tls_cache = tls_cache.clone();
+        let ip_tracker = ip_tracker.clone();
+        let beobachten = beobachten.clone();
+        let max_connections_tcp = max_connections.clone();
+
+        tokio::spawn(async move {
+            loop {
+                if !wait_until_admission_open(&mut admission_rx_tcp).await {
+                    warn!("Conditional-admission gate channel closed for tcp listener");
+                    break;
+                }
+                match listener.accept().await {
+                    Ok((stream, peer_addr)) => {
+                        let permit = match max_connections_tcp.clone().acquire_owned().await {
+                            Ok(permit) => permit,
+                            Err(_) => {
+                                error!("Connection limiter is closed");
+                                break;
+                            }
+                        };
+                        let config = config_rx.borrow_and_update().clone();
+                        let stats = stats.clone();
+                        let upstream_manager = upstream_manager.clone();
+                        let replay_checker = replay_checker.clone();
+                        let buffer_pool = buffer_pool.clone();
+                        let rng = rng.clone();
+                        let me_pool = me_pool.clone();
+                        let route_runtime = route_runtime.clone();
+                        let tls_cache = tls_cache.clone();
+                        let ip_tracker = ip_tracker.clone();
+                        let beobachten = beobachten.clone();
+                        let proxy_protocol_enabled = listener_proxy_protocol;
+                        let real_peer_report = Arc::new(std::sync::Mutex::new(None));
+                        let real_peer_report_for_handler = real_peer_report.clone();
+
+                        tokio::spawn(async move {
+                            let _permit = permit;
+                            if let Err(e) = ClientHandler::new(
+                                stream,
+                                peer_addr,
+                                config,
+                                stats,
+                                upstream_manager,
+                                replay_checker,
+                                buffer_pool,
+                                rng,
+                                me_pool,
+                                route_runtime,
+                                tls_cache,
+                                ip_tracker,
+                                beobachten,
+                                proxy_protocol_enabled,
+                                real_peer_report_for_handler,
+                            )
+                            .run()
+                            .await
+                            {
+                                let real_peer = match real_peer_report.lock() {
+                                    Ok(guard) => *guard,
+                                    Err(_) => None,
+                                };
+                                let peer_closed = matches!(
+                                    &e,
+                                    crate::error::ProxyError::Io(ioe)
+                                        if matches!(
+                                            ioe.kind(),
+                                            std::io::ErrorKind::ConnectionReset
+                                                | std::io::ErrorKind::ConnectionAborted
+                                                | std::io::ErrorKind::BrokenPipe
+                                                | std::io::ErrorKind::NotConnected
+                                        )
+                                ) || matches!(
+                                    &e,
+                                    crate::error::ProxyError::Stream(
+                                        crate::error::StreamError::Io(ioe)
+                                    )
+                                        if matches!(
+                                            ioe.kind(),
+                                            std::io::ErrorKind::ConnectionReset
+                                                | std::io::ErrorKind::ConnectionAborted
+                                                | std::io::ErrorKind::BrokenPipe
+                                                | std::io::ErrorKind::NotConnected
+                                        )
+                                );
+
+                                let me_closed = matches!(
+                                    &e,
+                                    crate::error::ProxyError::Proxy(msg) if msg == "ME connection lost"
+                                );
+                                let route_switched = matches!(
+                                    &e,
+                                    crate::error::ProxyError::Proxy(msg) if msg == ROUTE_SWITCH_ERROR_MSG
+                                );
+
+                                match (peer_closed, me_closed) {
+                                    (true, _) => {
+                                        if let Some(real_peer) = real_peer {
+                                            debug!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed by client");
+                                        } else {
+                                            debug!(peer = %peer_addr, error = %e, "Connection closed by client");
+                                        }
+                                    }
+                                    (_, true) => {
+                                        if let Some(real_peer) = real_peer {
+                                            warn!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed: Middle-End dropped session");
+                                        } else {
+                                            warn!(peer = %peer_addr, error = %e, "Connection closed: Middle-End dropped session");
+                                        }
+                                    }
+                                    _ if route_switched => {
+                                        if let Some(real_peer) = real_peer {
+                                            info!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed by controlled route cutover");
+                                        } else {
+                                            info!(peer = %peer_addr, error = %e, "Connection closed by controlled route cutover");
+                                        }
+                                    }
+                                    _ if is_expected_handshake_eof(&e) => {
+                                        if let Some(real_peer) = real_peer {
+                                            info!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed during initial handshake");
+                                        } else {
+                                            info!(peer = %peer_addr, error = %e, "Connection closed during initial handshake");
+                                        }
+                                    }
+                                    _ => {
+                                        if let Some(real_peer) = real_peer {
+                                            warn!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed with error");
+                                        } else {
+                                            warn!(peer = %peer_addr, error = %e, "Connection closed with error");
+                                        }
+                                    }
+                                }
+                            }
+                        });
+                    }
+                    Err(e) => {
+                        error!("Accept error: {}", e);
+                        tokio::time::sleep(Duration::from_millis(100)).await;
+                    }
+                }
+            }
+        });
+    }
+}

src/maestro/me_startup.rs

@@ -0,0 +1,516 @@
+use std::sync::Arc;
+use std::time::Duration;
+
+use tokio::sync::RwLock;
+use tracing::{error, info, warn};
+
+use crate::config::ProxyConfig;
+use crate::crypto::SecureRandom;
+use crate::network::probe::{NetworkDecision, NetworkProbe};
+use crate::startup::{
+    COMPONENT_ME_POOL_CONSTRUCT, COMPONENT_ME_POOL_INIT_STAGE1, COMPONENT_ME_PROXY_CONFIG_V4,
+    COMPONENT_ME_PROXY_CONFIG_V6, COMPONENT_ME_SECRET_FETCH, StartupMeStatus, StartupTracker,
+};
+use crate::stats::Stats;
+use crate::transport::middle_proxy::MePool;
+use crate::transport::UpstreamManager;
+
+use super::helpers::load_startup_proxy_config_snapshot;
+
+pub(crate) async fn initialize_me_pool(
+    use_middle_proxy: bool,
+    config: &ProxyConfig,
+    decision: &NetworkDecision,
+    probe: &NetworkProbe,
+    startup_tracker: &Arc<StartupTracker>,
+    upstream_manager: Arc<UpstreamManager>,
+    rng: Arc<SecureRandom>,
+    stats: Arc<Stats>,
+    api_me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
+) -> Option<Arc<MePool>> {
+    if !use_middle_proxy {
+        return None;
+    }
+
+    info!("=== Middle Proxy Mode ===");
+    let me_nat_probe = config.general.middle_proxy_nat_probe && config.network.stun_use;
+    if config.general.middle_proxy_nat_probe && !config.network.stun_use {
+        info!("Middle-proxy STUN probing disabled by network.stun_use=false");
+    }
+
+    let me2dc_fallback = config.general.me2dc_fallback;
+    let me_init_retry_attempts = config.general.me_init_retry_attempts;
+    let me_init_warn_after_attempts: u32 = 3;
+
+    // Global ad_tag (pool default). Used when user has no per-user tag in access.user_ad_tags.
+    let proxy_tag = config
+        .general
+        .ad_tag
+        .as_ref()
+        .map(|tag| hex::decode(tag).expect("general.ad_tag must be validated before startup"));
+
+    // =============================================================
+    // CRITICAL: Download Telegram proxy-secret (NOT user secret!)
+    //
+    // C MTProxy uses TWO separate secrets:
+    //   -S flag    = 16-byte user secret for client obfuscation
+    //   --aes-pwd  = 32-512 byte binary file for ME RPC auth
+    //
+    // proxy-secret is from: https://core.telegram.org/getProxySecret
+    // =============================================================
+    let proxy_secret_path = config.general.proxy_secret_path.as_deref();
+    let pool_size = config.general.middle_proxy_pool_size.max(1);
+    let proxy_secret = loop {
+        match crate::transport::middle_proxy::fetch_proxy_secret(
+            proxy_secret_path,
+            config.general.proxy_secret_len_max,
+        )
+        .await
+        {
+            Ok(proxy_secret) => break Some(proxy_secret),
+            Err(e) => {
+                startup_tracker.set_me_last_error(Some(e.to_string())).await;
+                if me2dc_fallback {
+                    error!(
+                        error = %e,
+                        "ME startup failed: proxy-secret is unavailable and no saved secret found; falling back to direct mode"
+                    );
+                    break None;
+                }
+
+                warn!(
+                    error = %e,
+                    retry_in_secs = 2,
+                    "ME startup failed: proxy-secret is unavailable and no saved secret found; retrying because me2dc_fallback=false"
+                );
+                tokio::time::sleep(Duration::from_secs(2)).await;
+            }
+        }
+    };
+    match proxy_secret {
+        Some(proxy_secret) => {
+            startup_tracker
+                .complete_component(
+                    COMPONENT_ME_SECRET_FETCH,
+                    Some("proxy-secret loaded".to_string()),
+                )
+                .await;
+            info!(
+                secret_len = proxy_secret.len(),
+                key_sig = format_args!(
+                    "0x{:08x}",
+                    if proxy_secret.len() >= 4 {
+                        u32::from_le_bytes([
+                            proxy_secret[0],
+                            proxy_secret[1],
+                            proxy_secret[2],
+                            proxy_secret[3],
+                        ])
+                    } else {
+                        0
+                    }
+                ),
+                "Proxy-secret loaded"
+            );
+
+            startup_tracker
+                .start_component(
+                    COMPONENT_ME_PROXY_CONFIG_V4,
+                    Some("load startup proxy-config v4".to_string()),
+                )
+                .await;
+            startup_tracker
+                .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_PROXY_CONFIG_V4)
+                .await;
+            let cfg_v4 = load_startup_proxy_config_snapshot(
+                "https://core.telegram.org/getProxyConfig",
+                config.general.proxy_config_v4_cache_path.as_deref(),
+                me2dc_fallback,
+                "getProxyConfig",
+            )
+            .await;
+            if cfg_v4.is_some() {
+                startup_tracker
+                    .complete_component(
+                        COMPONENT_ME_PROXY_CONFIG_V4,
+                        Some("proxy-config v4 loaded".to_string()),
+                    )
+                    .await;
+            } else {
+                startup_tracker
+                    .fail_component(
+                        COMPONENT_ME_PROXY_CONFIG_V4,
+                        Some("proxy-config v4 unavailable".to_string()),
+                    )
+                    .await;
+            }
+            startup_tracker
+                .start_component(
+                    COMPONENT_ME_PROXY_CONFIG_V6,
+                    Some("load startup proxy-config v6".to_string()),
+                )
+                .await;
+            startup_tracker
+                .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_PROXY_CONFIG_V6)
+                .await;
+            let cfg_v6 = load_startup_proxy_config_snapshot(
+                "https://core.telegram.org/getProxyConfigV6",
+                config.general.proxy_config_v6_cache_path.as_deref(),
+                me2dc_fallback,
+                "getProxyConfigV6",
+            )
+            .await;
+            if cfg_v6.is_some() {
+                startup_tracker
+                    .complete_component(
+                        COMPONENT_ME_PROXY_CONFIG_V6,
+                        Some("proxy-config v6 loaded".to_string()),
+                    )
+                    .await;
+            } else {
+                startup_tracker
+                    .fail_component(
+                        COMPONENT_ME_PROXY_CONFIG_V6,
+                        Some("proxy-config v6 unavailable".to_string()),
+                    )
+                    .await;
+            }
+
+            if let (Some(cfg_v4), Some(cfg_v6)) = (cfg_v4, cfg_v6) {
+                startup_tracker
+                    .start_component(
+                        COMPONENT_ME_POOL_CONSTRUCT,
+                        Some("construct ME pool".to_string()),
+                    )
+                    .await;
+                startup_tracker
+                    .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_POOL_CONSTRUCT)
+                    .await;
+                let pool = MePool::new(
+                    proxy_tag.clone(),
+                    proxy_secret,
+                    config.general.middle_proxy_nat_ip,
+                    me_nat_probe,
+                    None,
+                    config.network.stun_servers.clone(),
+                    config.general.stun_nat_probe_concurrency,
+                    probe.detected_ipv6,
+                    config.timeouts.me_one_retry,
+                    config.timeouts.me_one_timeout_ms,
+                    cfg_v4.map.clone(),
+                    cfg_v6.map.clone(),
+                    cfg_v4.default_dc.or(cfg_v6.default_dc),
+                    decision.clone(),
+                    Some(upstream_manager.clone()),
+                    rng.clone(),
+                    stats.clone(),
+                    config.general.me_keepalive_enabled,
+                    config.general.me_keepalive_interval_secs,
+                    config.general.me_keepalive_jitter_secs,
+                    config.general.me_keepalive_payload_random,
+                    config.general.rpc_proxy_req_every,
+                    config.general.me_warmup_stagger_enabled,
+                    config.general.me_warmup_step_delay_ms,
+                    config.general.me_warmup_step_jitter_ms,
+                    config.general.me_reconnect_max_concurrent_per_dc,
+                    config.general.me_reconnect_backoff_base_ms,
+                    config.general.me_reconnect_backoff_cap_ms,
+                    config.general.me_reconnect_fast_retry_count,
+                    config.general.me_single_endpoint_shadow_writers,
+                    config.general.me_single_endpoint_outage_mode_enabled,
+                    config.general.me_single_endpoint_outage_disable_quarantine,
+                    config.general.me_single_endpoint_outage_backoff_min_ms,
+                    config.general.me_single_endpoint_outage_backoff_max_ms,
+                    config.general.me_single_endpoint_shadow_rotate_every_secs,
+                    config.general.me_floor_mode,
+                    config.general.me_adaptive_floor_idle_secs,
+                    config.general.me_adaptive_floor_min_writers_single_endpoint,
+                    config.general.me_adaptive_floor_min_writers_multi_endpoint,
+                    config.general.me_adaptive_floor_recover_grace_secs,
+                    config.general.me_adaptive_floor_writers_per_core_total,
+                    config.general.me_adaptive_floor_cpu_cores_override,
+                    config.general.me_adaptive_floor_max_extra_writers_single_per_core,
+                    config.general.me_adaptive_floor_max_extra_writers_multi_per_core,
+                    config.general.me_adaptive_floor_max_active_writers_per_core,
+                    config.general.me_adaptive_floor_max_warm_writers_per_core,
+                    config.general.me_adaptive_floor_max_active_writers_global,
+                    config.general.me_adaptive_floor_max_warm_writers_global,
+                    config.general.hardswap,
+                    config.general.me_pool_drain_ttl_secs,
+                    config.general.me_pool_drain_threshold,
+                    config.general.effective_me_pool_force_close_secs(),
+                    config.general.me_pool_min_fresh_ratio,
+                    config.general.me_hardswap_warmup_delay_min_ms,
+                    config.general.me_hardswap_warmup_delay_max_ms,
+                    config.general.me_hardswap_warmup_extra_passes,
+                    config.general.me_hardswap_warmup_pass_backoff_base_ms,
+                    config.general.me_bind_stale_mode,
+                    config.general.me_bind_stale_ttl_secs,
+                    config.general.me_secret_atomic_snapshot,
+                    config.general.me_deterministic_writer_sort,
+                    config.general.me_writer_pick_mode,
+                    config.general.me_writer_pick_sample_size,
+                    config.general.me_socks_kdf_policy,
+                    config.general.me_writer_cmd_channel_capacity,
+                    config.general.me_route_channel_capacity,
+                    config.general.me_route_backpressure_base_timeout_ms,
+                    config.general.me_route_backpressure_high_timeout_ms,
+                    config.general.me_route_backpressure_high_watermark_pct,
+                    config.general.me_reader_route_data_wait_ms,
+                    config.general.me_health_interval_ms_unhealthy,
+                    config.general.me_health_interval_ms_healthy,
+                    config.general.me_warn_rate_limit_ms,
+                    config.general.me_route_no_writer_mode,
+                    config.general.me_route_no_writer_wait_ms,
+                    config.general.me_route_inline_recovery_attempts,
+                    config.general.me_route_inline_recovery_wait_ms,
+                );
+                startup_tracker
+                    .complete_component(
+                        COMPONENT_ME_POOL_CONSTRUCT,
+                        Some("ME pool object created".to_string()),
+                    )
+                    .await;
+                *api_me_pool.write().await = Some(pool.clone());
+                startup_tracker
+                    .start_component(
+                        COMPONENT_ME_POOL_INIT_STAGE1,
+                        Some("initialize ME pool writers".to_string()),
+                    )
+                    .await;
+                startup_tracker
+                    .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_POOL_INIT_STAGE1)
+                    .await;
+
+                if me2dc_fallback {
+                    let pool_bg = pool.clone();
+                    let rng_bg = rng.clone();
+                    let startup_tracker_bg = startup_tracker.clone();
+                    let retry_limit = if me_init_retry_attempts == 0 {
+                        String::from("unlimited")
+                    } else {
+                        me_init_retry_attempts.to_string()
+                    };
+                    std::thread::spawn(move || {
+                        let runtime = match tokio::runtime::Builder::new_current_thread()
+                            .enable_all()
+                            .build()
+                        {
+                            Ok(runtime) => runtime,
+                            Err(error) => {
+                                error!(error = %error, "Failed to build background runtime for ME initialization");
+                                return;
+                            }
+                        };
+                        runtime.block_on(async move {
+                            let mut init_attempt: u32 = 0;
+                            loop {
+                                init_attempt = init_attempt.saturating_add(1);
+                                startup_tracker_bg.set_me_init_attempt(init_attempt).await;
+                                match pool_bg.init(pool_size, &rng_bg).await {
+                                    Ok(()) => {
+                                        startup_tracker_bg.set_me_last_error(None).await;
+                                        startup_tracker_bg
+                                            .complete_component(
+                                                COMPONENT_ME_POOL_INIT_STAGE1,
+                                                Some("ME pool initialized".to_string()),
+                                            )
+                                            .await;
+                                        startup_tracker_bg
+                                            .set_me_status(StartupMeStatus::Ready, "ready")
+                                            .await;
+                                        info!(
+                                            attempt = init_attempt,
+                                            "Middle-End pool initialized successfully"
+                                        );
+
+                                        let pool_health = pool_bg.clone();
+                                        let rng_health = rng_bg.clone();
+                                        let min_conns = pool_size;
+                                        tokio::spawn(async move {
+                                            crate::transport::middle_proxy::me_health_monitor(
+                                                pool_health,
+                                                rng_health,
+                                                min_conns,
+                                            )
+                                            .await;
+                                        });
+                                        break;
+                                    }
+                                    Err(e) => {
+                                        startup_tracker_bg.set_me_last_error(Some(e.to_string())).await;
+                                        if init_attempt >= me_init_warn_after_attempts {
+                                            warn!(
+                                                error = %e,
+                                                attempt = init_attempt,
+                                                retry_limit = %retry_limit,
+                                                retry_in_secs = 2,
+                                                "ME pool is not ready yet; retrying background initialization"
+                                            );
+                                        } else {
+                                            info!(
+                                                error = %e,
+                                                attempt = init_attempt,
+                                                retry_limit = %retry_limit,
+                                                retry_in_secs = 2,
+                                                "ME pool startup warmup: retrying background initialization"
+                                            );
+                                        }
+                                        pool_bg.reset_stun_state();
+                                        tokio::time::sleep(Duration::from_secs(2)).await;
+                                    }
+                                }
+                            }
+                        });
+                    });
+                    startup_tracker
+                        .set_me_status(StartupMeStatus::Initializing, "background_init")
+                        .await;
+                    info!(
+                        startup_grace_secs = 80,
+                        "ME pool initialization continues in background; startup continues with conditional Direct fallback"
+                    );
+                    Some(pool)
+                } else {
+                    let mut init_attempt: u32 = 0;
+                    loop {
+                        init_attempt = init_attempt.saturating_add(1);
+                        startup_tracker.set_me_init_attempt(init_attempt).await;
+                        match pool.init(pool_size, &rng).await {
+                            Ok(()) => {
+                                startup_tracker.set_me_last_error(None).await;
+                                startup_tracker
+                                    .complete_component(
+                                        COMPONENT_ME_POOL_INIT_STAGE1,
+                                        Some("ME pool initialized".to_string()),
+                                    )
+                                    .await;
+                                startup_tracker
+                                    .set_me_status(StartupMeStatus::Ready, "ready")
+                                    .await;
+                                info!(
+                                    attempt = init_attempt,
+                                    "Middle-End pool initialized successfully"
+                                );
+
+                                let pool_clone = pool.clone();
+                                let rng_clone = rng.clone();
+                                let min_conns = pool_size;
+                                tokio::spawn(async move {
+                                    crate::transport::middle_proxy::me_health_monitor(
+                                        pool_clone, rng_clone, min_conns,
+                                    )
+                                    .await;
+                                });
+
+                                break Some(pool);
+                            }
+                            Err(e) => {
+                                startup_tracker.set_me_last_error(Some(e.to_string())).await;
+                                let retries_limited = me_init_retry_attempts > 0;
+                                if retries_limited && init_attempt >= me_init_retry_attempts {
+                                    startup_tracker
+                                        .fail_component(
+                                            COMPONENT_ME_POOL_INIT_STAGE1,
+                                            Some("ME init retry budget exhausted".to_string()),
+                                        )
+                                        .await;
+                                    startup_tracker
+                                        .set_me_status(StartupMeStatus::Failed, "failed")
+                                        .await;
+                                    error!(
+                                        error = %e,
+                                        attempt = init_attempt,
+                                        retry_limit = me_init_retry_attempts,
+                                        "ME pool init retries exhausted; startup cannot continue in middle-proxy mode"
+                                    );
+                                    break None;
+                                }
+
+                                let retry_limit = if me_init_retry_attempts == 0 {
+                                    String::from("unlimited")
+                                } else {
+                                    me_init_retry_attempts.to_string()
+                                };
+                                if init_attempt >= me_init_warn_after_attempts {
+                                    warn!(
+                                        error = %e,
+                                        attempt = init_attempt,
+                                        retry_limit = retry_limit,
+                                        me2dc_fallback = me2dc_fallback,
+                                        retry_in_secs = 2,
+                                        "ME pool is not ready yet; retrying startup initialization"
+                                    );
+                                } else {
+                                    info!(
+                                        error = %e,
+                                        attempt = init_attempt,
+                                        retry_limit = retry_limit,
+                                        me2dc_fallback = me2dc_fallback,
+                                        retry_in_secs = 2,
+                                        "ME pool startup warmup: retrying initialization"
+                                    );
+                                }
+                                pool.reset_stun_state();
+                                tokio::time::sleep(Duration::from_secs(2)).await;
+                            }
+                        }
+                    }
+                }
+            } else {
+                startup_tracker
+                    .skip_component(
+                        COMPONENT_ME_POOL_CONSTRUCT,
+                        Some("ME configs are incomplete".to_string()),
+                    )
+                    .await;
+                startup_tracker
+                    .fail_component(
+                        COMPONENT_ME_POOL_INIT_STAGE1,
+                        Some("ME configs are incomplete".to_string()),
+                    )
+                    .await;
+                startup_tracker
+                    .set_me_status(StartupMeStatus::Failed, "failed")
+                    .await;
+                None
+            }
+        }
+        None => {
+            startup_tracker
+                .fail_component(
+                    COMPONENT_ME_SECRET_FETCH,
+                    Some("proxy-secret unavailable".to_string()),
+                )
+                .await;
+            startup_tracker
+                .skip_component(
+                    COMPONENT_ME_PROXY_CONFIG_V4,
+                    Some("proxy-secret unavailable".to_string()),
+                )
+                .await;
+            startup_tracker
+                .skip_component(
+                    COMPONENT_ME_PROXY_CONFIG_V6,
+                    Some("proxy-secret unavailable".to_string()),
+                )
+                .await;
+            startup_tracker
+                .skip_component(
+                    COMPONENT_ME_POOL_CONSTRUCT,
+                    Some("proxy-secret unavailable".to_string()),
+                )
+                .await;
+            startup_tracker
+                .fail_component(
+                    COMPONENT_ME_POOL_INIT_STAGE1,
+                    Some("proxy-secret unavailable".to_string()),
+                )
+                .await;
+            startup_tracker
+                .set_me_status(StartupMeStatus::Failed, "failed")
+                .await;
+            None
+        }
+    }
+}

src/maestro/mod.rs

@@ -0,0 +1,598 @@
+//! telemt — Telegram MTProto Proxy
+
+#![allow(unused_assignments)]
+
+// Runtime orchestration modules.
+// - helpers: CLI and shared startup/runtime helper routines.
+// - tls_bootstrap: TLS front cache bootstrap and refresh tasks.
+// - me_startup: Middle-End secret/config fetch and pool initialization.
+// - connectivity: startup ME/DC connectivity diagnostics.
+// - runtime_tasks: hot-reload and background task orchestration.
+// - admission: conditional-cast gate and route mode switching.
+// - listeners: TCP/Unix listener bind and accept-loop orchestration.
+// - shutdown: graceful shutdown sequence and uptime logging.
+mod helpers;
+mod admission;
+mod connectivity;
+mod listeners;
+mod me_startup;
+mod runtime_tasks;
+mod shutdown;
+mod tls_bootstrap;
+
+use std::net::{IpAddr, SocketAddr};
+use std::sync::Arc;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::sync::{RwLock, Semaphore, watch};
+use tracing::{error, info, warn};
+use tracing_subscriber::{EnvFilter, fmt, prelude::*, reload};
+
+use crate::api;
+use crate::config::{LogLevel, ProxyConfig};
+use crate::crypto::SecureRandom;
+use crate::ip_tracker::UserIpTracker;
+use crate::network::probe::{decide_network_capabilities, log_probe_result, run_probe};
+use crate::proxy::route_mode::{RelayRouteMode, RouteRuntimeController};
+use crate::stats::beobachten::BeobachtenStore;
+use crate::stats::telemetry::TelemetryPolicy;
+use crate::stats::{ReplayChecker, Stats};
+use crate::startup::{
+    COMPONENT_API_BOOTSTRAP, COMPONENT_CONFIG_LOAD,
+    COMPONENT_ME_POOL_CONSTRUCT, COMPONENT_ME_POOL_INIT_STAGE1,
+    COMPONENT_ME_PROXY_CONFIG_V4, COMPONENT_ME_PROXY_CONFIG_V6, COMPONENT_ME_SECRET_FETCH,
+    COMPONENT_NETWORK_PROBE, COMPONENT_TRACING_INIT, StartupMeStatus, StartupTracker,
+};
+use crate::stream::BufferPool;
+use crate::transport::middle_proxy::MePool;
+use crate::transport::UpstreamManager;
+use helpers::parse_cli;
+
+/// Runs the full telemt runtime startup pipeline and blocks until shutdown.
+pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
+    let process_started_at = Instant::now();
+    let process_started_at_epoch_secs = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs();
+    let startup_tracker = Arc::new(StartupTracker::new(process_started_at_epoch_secs));
+    startup_tracker
+        .start_component(COMPONENT_CONFIG_LOAD, Some("load and validate config".to_string()))
+        .await;
+    let (config_path, data_path, cli_silent, cli_log_level) = parse_cli();
+
+    let mut config = match ProxyConfig::load(&config_path) {
+        Ok(c) => c,
+        Err(e) => {
+            if std::path::Path::new(&config_path).exists() {
+                eprintln!("[telemt] Error: {}", e);
+                std::process::exit(1);
+            } else {
+                let default = ProxyConfig::default();
+                std::fs::write(&config_path, toml::to_string_pretty(&default).unwrap()).unwrap();
+                eprintln!("[telemt] Created default config at {}", config_path);
+                default
+            }
+        }
+    };
+
+    if let Err(e) = config.validate() {
+        eprintln!("[telemt] Invalid config: {}", e);
+        std::process::exit(1);
+    }
+
+    if let Some(p) = data_path {
+        config.general.data_path = Some(p);
+    }
+
+    if let Some(ref data_path) = config.general.data_path {
+        if !data_path.is_absolute() {
+            eprintln!("[telemt] data_path must be absolute: {}", data_path.display());
+            std::process::exit(1);
+        }
+
+        if data_path.exists() {
+            if !data_path.is_dir() {
+                eprintln!("[telemt] data_path exists but is not a directory: {}", data_path.display());
+                std::process::exit(1);
+            }
+        } else {
+            if let Err(e) = std::fs::create_dir_all(data_path) {
+                eprintln!("[telemt] Can't create data_path {}: {}", data_path.display(), e);
+                std::process::exit(1);
+            }
+        }
+
+        if let Err(e) = std::env::set_current_dir(data_path) {
+            eprintln!("[telemt] Can't use data_path {}: {}", data_path.display(), e);
+            std::process::exit(1);
+        }
+    }
+
+    if let Err(e) = crate::network::dns_overrides::install_entries(&config.network.dns_overrides) {
+        eprintln!("[telemt] Invalid network.dns_overrides: {}", e);
+        std::process::exit(1);
+    }
+    startup_tracker
+        .complete_component(COMPONENT_CONFIG_LOAD, Some("config is ready".to_string()))
+        .await;
+
+    let has_rust_log = std::env::var("RUST_LOG").is_ok();
+    let effective_log_level = if cli_silent {
+        LogLevel::Silent
+    } else if let Some(ref s) = cli_log_level {
+        LogLevel::from_str_loose(s)
+    } else {
+        config.general.log_level.clone()
+    };
+
+    let (filter_layer, filter_handle) = reload::Layer::new(EnvFilter::new("info"));
+    startup_tracker
+        .start_component(COMPONENT_TRACING_INIT, Some("initialize tracing subscriber".to_string()))
+        .await;
+
+    // Configure color output based on config
+    let fmt_layer = if config.general.disable_colors {
+        fmt::Layer::default().with_ansi(false)
+    } else {
+        fmt::Layer::default().with_ansi(true)
+    };
+
+    tracing_subscriber::registry()
+        .with(filter_layer)
+        .with(fmt_layer)
+        .init();
+    startup_tracker
+        .complete_component(COMPONENT_TRACING_INIT, Some("tracing initialized".to_string()))
+        .await;
+
+    info!("Telemt MTProxy v{}", env!("CARGO_PKG_VERSION"));
+    info!("Log level: {}", effective_log_level);
+    if config.general.disable_colors {
+        info!("Colors: disabled");
+    }
+    info!(
+        "Modes: classic={} secure={} tls={}",
+        config.general.modes.classic, config.general.modes.secure, config.general.modes.tls
+    );
+    if config.general.modes.classic {
+        warn!("Classic mode is vulnerable to DPI detection; enable only for legacy clients");
+    }
+    info!("TLS domain: {}", config.censorship.tls_domain);
+    if let Some(ref sock) = config.censorship.mask_unix_sock {
+        info!("Mask: {} -> unix:{}", config.censorship.mask, sock);
+        if !std::path::Path::new(sock).exists() {
+            warn!(
+                "Unix socket '{}' does not exist yet. Masking will fail until it appears.",
+                sock
+            );
+        }
+    } else {
+        info!(
+            "Mask: {} -> {}:{}",
+            config.censorship.mask,
+            config
+                .censorship
+                .mask_host
+                .as_deref()
+                .unwrap_or(&config.censorship.tls_domain),
+            config.censorship.mask_port
+        );
+    }
+
+    if config.censorship.tls_domain == "www.google.com" {
+        warn!("Using default tls_domain. Consider setting a custom domain.");
+    }
+
+    let stats = Arc::new(Stats::new());
+    stats.apply_telemetry_policy(TelemetryPolicy::from_config(&config.general.telemetry));
+
+    let upstream_manager = Arc::new(UpstreamManager::new(
+        config.upstreams.clone(),
+        config.general.upstream_connect_retry_attempts,
+        config.general.upstream_connect_retry_backoff_ms,
+        config.general.upstream_connect_budget_ms,
+        config.general.upstream_unhealthy_fail_threshold,
+        config.general.upstream_connect_failfast_hard_errors,
+        stats.clone(),
+    ));
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker
+        .load_limits(
+            config.access.user_max_unique_ips_global_each,
+            &config.access.user_max_unique_ips,
+        )
+        .await;
+    ip_tracker
+        .set_limit_policy(
+            config.access.user_max_unique_ips_mode,
+            config.access.user_max_unique_ips_window_secs,
+        )
+        .await;
+    if config.access.user_max_unique_ips_global_each > 0 || !config.access.user_max_unique_ips.is_empty()
+    {
+        info!(
+            global_each_limit = config.access.user_max_unique_ips_global_each,
+            explicit_user_limits = config.access.user_max_unique_ips.len(),
+            "User unique IP limits configured"
+        );
+    }
+    if !config.network.dns_overrides.is_empty() {
+        info!(
+            "Runtime DNS overrides configured: {} entries",
+            config.network.dns_overrides.len()
+        );
+    }
+
+    let (api_config_tx, api_config_rx) = watch::channel(Arc::new(config.clone()));
+    let (detected_ips_tx, detected_ips_rx) = watch::channel((None::<IpAddr>, None::<IpAddr>));
+    let initial_admission_open = !config.general.use_middle_proxy;
+    let (admission_tx, admission_rx) = watch::channel(initial_admission_open);
+    let initial_route_mode = if config.general.use_middle_proxy {
+        RelayRouteMode::Middle
+    } else {
+        RelayRouteMode::Direct
+    };
+    let route_runtime = Arc::new(RouteRuntimeController::new(initial_route_mode));
+    let api_me_pool = Arc::new(RwLock::new(None::<Arc<MePool>>));
+    startup_tracker
+        .start_component(COMPONENT_API_BOOTSTRAP, Some("spawn API listener task".to_string()))
+        .await;
+
+    if config.server.api.enabled {
+        let listen = match config.server.api.listen.parse::<SocketAddr>() {
+            Ok(listen) => listen,
+            Err(error) => {
+                warn!(
+                    error = %error,
+                    listen = %config.server.api.listen,
+                    "Invalid server.api.listen; API is disabled"
+                );
+                SocketAddr::from(([127, 0, 0, 1], 0))
+            }
+        };
+        if listen.port() != 0 {
+            let stats_api = stats.clone();
+            let ip_tracker_api = ip_tracker.clone();
+            let me_pool_api = api_me_pool.clone();
+            let upstream_manager_api = upstream_manager.clone();
+            let route_runtime_api = route_runtime.clone();
+            let config_rx_api = api_config_rx.clone();
+            let admission_rx_api = admission_rx.clone();
+            let config_path_api = std::path::PathBuf::from(&config_path);
+            let startup_tracker_api = startup_tracker.clone();
+            let detected_ips_rx_api = detected_ips_rx.clone();
+            tokio::spawn(async move {
+                api::serve(
+                    listen,
+                    stats_api,
+                    ip_tracker_api,
+                    me_pool_api,
+                    route_runtime_api,
+                    upstream_manager_api,
+                    config_rx_api,
+                    admission_rx_api,
+                    config_path_api,
+                    detected_ips_rx_api,
+                    process_started_at_epoch_secs,
+                    startup_tracker_api,
+                )
+                .await;
+            });
+            startup_tracker
+                .complete_component(
+                    COMPONENT_API_BOOTSTRAP,
+                    Some(format!("api task spawned on {}", listen)),
+                )
+                .await;
+        } else {
+            startup_tracker
+                .skip_component(
+                    COMPONENT_API_BOOTSTRAP,
+                    Some("server.api.listen has zero port".to_string()),
+                )
+                .await;
+        }
+    } else {
+        startup_tracker
+            .skip_component(
+                COMPONENT_API_BOOTSTRAP,
+                Some("server.api.enabled is false".to_string()),
+            )
+            .await;
+    }
+
+    let mut tls_domains = Vec::with_capacity(1 + config.censorship.tls_domains.len());
+    tls_domains.push(config.censorship.tls_domain.clone());
+    for d in &config.censorship.tls_domains {
+        if !tls_domains.contains(d) {
+            tls_domains.push(d.clone());
+        }
+    }
+
+    let tls_cache = tls_bootstrap::bootstrap_tls_front(
+        &config,
+        &tls_domains,
+        upstream_manager.clone(),
+        &startup_tracker,
+    )
+    .await;
+
+    startup_tracker
+        .start_component(COMPONENT_NETWORK_PROBE, Some("probe network capabilities".to_string()))
+        .await;
+    let probe = run_probe(
+        &config.network,
+        &config.upstreams,
+        config.general.middle_proxy_nat_probe,
+        config.general.stun_nat_probe_concurrency,
+    )
+    .await?;
+    detected_ips_tx.send_replace((
+        probe.detected_ipv4.map(IpAddr::V4),
+        probe.detected_ipv6.map(IpAddr::V6),
+    ));
+    let decision = decide_network_capabilities(
+        &config.network,
+        &probe,
+        config.general.middle_proxy_nat_ip,
+    );
+    log_probe_result(&probe, &decision);
+    startup_tracker
+        .complete_component(
+            COMPONENT_NETWORK_PROBE,
+            Some("network capabilities determined".to_string()),
+        )
+        .await;
+
+    let prefer_ipv6 = decision.prefer_ipv6();
+    let mut use_middle_proxy = config.general.use_middle_proxy;
+    let beobachten = Arc::new(BeobachtenStore::new());
+    let rng = Arc::new(SecureRandom::new());
+
+    // Connection concurrency limit (0 = unlimited)
+    let max_connections_limit = if config.server.max_connections == 0 {
+        Semaphore::MAX_PERMITS
+    } else {
+        config.server.max_connections as usize
+    };
+    let max_connections = Arc::new(Semaphore::new(max_connections_limit));
+
+    let me2dc_fallback = config.general.me2dc_fallback;
+    let me_init_retry_attempts = config.general.me_init_retry_attempts;
+    if use_middle_proxy && !decision.ipv4_me && !decision.ipv6_me {
+        if me2dc_fallback {
+            warn!("No usable IP family for Middle Proxy detected; falling back to direct DC");
+            use_middle_proxy = false;
+        } else {
+            warn!(
+                "No usable IP family for Middle Proxy detected; me2dc_fallback=false, ME init retries stay active"
+            );
+        }
+    }
+
+    if use_middle_proxy {
+        startup_tracker
+            .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_SECRET_FETCH)
+            .await;
+        startup_tracker
+            .start_component(
+                COMPONENT_ME_SECRET_FETCH,
+                Some("fetch proxy-secret from source/cache".to_string()),
+            )
+            .await;
+        startup_tracker
+            .set_me_retry_limit(if !me2dc_fallback || me_init_retry_attempts == 0 {
+                "unlimited".to_string()
+            } else {
+                me_init_retry_attempts.to_string()
+            })
+            .await;
+    } else {
+        startup_tracker
+            .set_me_status(StartupMeStatus::Skipped, "skipped")
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_SECRET_FETCH,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_PROXY_CONFIG_V4,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_PROXY_CONFIG_V6,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_POOL_CONSTRUCT,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_POOL_INIT_STAGE1,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+    }
+
+    let me_pool: Option<Arc<MePool>> = me_startup::initialize_me_pool(
+        use_middle_proxy,
+        &config,
+        &decision,
+        &probe,
+        &startup_tracker,
+        upstream_manager.clone(),
+        rng.clone(),
+        stats.clone(),
+        api_me_pool.clone(),
+    )
+    .await;
+
+    // If ME failed to initialize, force direct-only mode.
+    if me_pool.is_some() {
+        startup_tracker
+            .set_transport_mode("middle_proxy")
+            .await;
+        startup_tracker
+            .set_degraded(false)
+            .await;
+        info!("Transport: Middle-End Proxy - all DC-over-RPC");
+    } else {
+        let _ = use_middle_proxy;
+        use_middle_proxy = false;
+        // Make runtime config reflect direct-only mode for handlers.
+        config.general.use_middle_proxy = false;
+        startup_tracker
+            .set_transport_mode("direct")
+            .await;
+        startup_tracker
+            .set_degraded(true)
+            .await;
+        if me2dc_fallback {
+            startup_tracker
+                .set_me_status(StartupMeStatus::Failed, "fallback_to_direct")
+                .await;
+        } else {
+            startup_tracker
+                .set_me_status(StartupMeStatus::Skipped, "skipped")
+                .await;
+        }
+        info!("Transport: Direct DC - TCP - standard DC-over-TCP");
+    }
+
+    // Freeze config after possible fallback decision
+    let config = Arc::new(config);
+
+    let replay_checker = Arc::new(ReplayChecker::new(
+        config.access.replay_check_len,
+        Duration::from_secs(config.access.replay_window_secs),
+    ));
+
+    let buffer_pool = Arc::new(BufferPool::with_config(16 * 1024, 4096));
+
+    connectivity::run_startup_connectivity(
+        &config,
+        &me_pool,
+        rng.clone(),
+        &startup_tracker,
+        upstream_manager.clone(),
+        prefer_ipv6,
+        &decision,
+        process_started_at,
+        api_me_pool.clone(),
+    )
+    .await;
+
+    let runtime_watches = runtime_tasks::spawn_runtime_tasks(
+        &config,
+        &config_path,
+        &probe,
+        prefer_ipv6,
+        decision.ipv4_dc,
+        decision.ipv6_dc,
+        &startup_tracker,
+        stats.clone(),
+        upstream_manager.clone(),
+        replay_checker.clone(),
+        me_pool.clone(),
+        rng.clone(),
+        ip_tracker.clone(),
+        beobachten.clone(),
+        api_config_tx.clone(),
+        me_pool.clone(),
+    )
+    .await;
+    let config_rx = runtime_watches.config_rx;
+    let log_level_rx = runtime_watches.log_level_rx;
+    let detected_ip_v4 = runtime_watches.detected_ip_v4;
+    let detected_ip_v6 = runtime_watches.detected_ip_v6;
+
+    admission::configure_admission_gate(
+        &config,
+        me_pool.clone(),
+        route_runtime.clone(),
+        &admission_tx,
+        config_rx.clone(),
+    )
+    .await;
+    let _admission_tx_hold = admission_tx;
+
+    let bound = listeners::bind_listeners(
+        &config,
+        decision.ipv4_dc,
+        decision.ipv6_dc,
+        detected_ip_v4,
+        detected_ip_v6,
+        &startup_tracker,
+        config_rx.clone(),
+        admission_rx.clone(),
+        stats.clone(),
+        upstream_manager.clone(),
+        replay_checker.clone(),
+        buffer_pool.clone(),
+        rng.clone(),
+        me_pool.clone(),
+        route_runtime.clone(),
+        tls_cache.clone(),
+        ip_tracker.clone(),
+        beobachten.clone(),
+        max_connections.clone(),
+    )
+    .await?;
+    let listeners = bound.listeners;
+    let has_unix_listener = bound.has_unix_listener;
+
+    if listeners.is_empty() && !has_unix_listener {
+        error!("No listeners. Exiting.");
+        std::process::exit(1);
+    }
+
+    runtime_tasks::apply_runtime_log_filter(
+        has_rust_log,
+        &effective_log_level,
+        filter_handle,
+        log_level_rx,
+    )
+    .await;
+
+    runtime_tasks::spawn_metrics_if_configured(
+        &config,
+        &startup_tracker,
+        stats.clone(),
+        beobachten.clone(),
+        ip_tracker.clone(),
+        config_rx.clone(),
+    )
+    .await;
+
+    runtime_tasks::mark_runtime_ready(&startup_tracker).await;
+
+    listeners::spawn_tcp_accept_loops(
+        listeners,
+        config_rx.clone(),
+        admission_rx.clone(),
+        stats.clone(),
+        upstream_manager.clone(),
+        replay_checker.clone(),
+        buffer_pool.clone(),
+        rng.clone(),
+        me_pool.clone(),
+        route_runtime.clone(),
+        tls_cache.clone(),
+        ip_tracker.clone(),
+        beobachten.clone(),
+        max_connections.clone(),
+    );
+
+    shutdown::wait_for_shutdown(process_started_at, me_pool).await;
+
+    Ok(())
+}

src/maestro/runtime_tasks.rs

@@ -0,0 +1,351 @@
+use std::net::IpAddr;
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use tokio::sync::{mpsc, watch};
+use tracing::{debug, warn};
+use tracing_subscriber::reload;
+use tracing_subscriber::EnvFilter;
+
+use crate::config::{LogLevel, ProxyConfig};
+use crate::config::hot_reload::spawn_config_watcher;
+use crate::crypto::SecureRandom;
+use crate::ip_tracker::UserIpTracker;
+use crate::metrics;
+use crate::network::probe::NetworkProbe;
+use crate::startup::{COMPONENT_CONFIG_WATCHER_START, COMPONENT_METRICS_START, COMPONENT_RUNTIME_READY, StartupTracker};
+use crate::stats::beobachten::BeobachtenStore;
+use crate::stats::telemetry::TelemetryPolicy;
+use crate::stats::{ReplayChecker, Stats};
+use crate::transport::middle_proxy::{MePool, MeReinitTrigger};
+use crate::transport::UpstreamManager;
+
+use super::helpers::write_beobachten_snapshot;
+
+pub(crate) struct RuntimeWatches {
+    pub(crate) config_rx: watch::Receiver<Arc<ProxyConfig>>,
+    pub(crate) log_level_rx: watch::Receiver<LogLevel>,
+    pub(crate) detected_ip_v4: Option<IpAddr>,
+    pub(crate) detected_ip_v6: Option<IpAddr>,
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn spawn_runtime_tasks(
+    config: &Arc<ProxyConfig>,
+    config_path: &str,
+    probe: &NetworkProbe,
+    prefer_ipv6: bool,
+    decision_ipv4_dc: bool,
+    decision_ipv6_dc: bool,
+    startup_tracker: &Arc<StartupTracker>,
+    stats: Arc<Stats>,
+    upstream_manager: Arc<UpstreamManager>,
+    replay_checker: Arc<ReplayChecker>,
+    me_pool: Option<Arc<MePool>>,
+    rng: Arc<SecureRandom>,
+    ip_tracker: Arc<UserIpTracker>,
+    beobachten: Arc<BeobachtenStore>,
+    api_config_tx: watch::Sender<Arc<ProxyConfig>>,
+    me_pool_for_policy: Option<Arc<MePool>>,
+) -> RuntimeWatches {
+    let um_clone = upstream_manager.clone();
+    let dc_overrides_for_health = config.dc_overrides.clone();
+    tokio::spawn(async move {
+        um_clone
+            .run_health_checks(
+                prefer_ipv6,
+                decision_ipv4_dc,
+                decision_ipv6_dc,
+                dc_overrides_for_health,
+            )
+            .await;
+    });
+
+    let rc_clone = replay_checker.clone();
+    tokio::spawn(async move {
+        rc_clone.run_periodic_cleanup().await;
+    });
+
+    let detected_ip_v4: Option<IpAddr> = probe.detected_ipv4.map(IpAddr::V4);
+    let detected_ip_v6: Option<IpAddr> = probe.detected_ipv6.map(IpAddr::V6);
+    debug!(
+        "Detected IPs: v4={:?} v6={:?}",
+        detected_ip_v4, detected_ip_v6
+    );
+
+    startup_tracker
+        .start_component(
+            COMPONENT_CONFIG_WATCHER_START,
+            Some("spawn config hot-reload watcher".to_string()),
+        )
+        .await;
+    let (config_rx, log_level_rx): (
+        watch::Receiver<Arc<ProxyConfig>>,
+        watch::Receiver<LogLevel>,
+    ) = spawn_config_watcher(
+        PathBuf::from(config_path),
+        config.clone(),
+        detected_ip_v4,
+        detected_ip_v6,
+    );
+    startup_tracker
+        .complete_component(
+            COMPONENT_CONFIG_WATCHER_START,
+            Some("config hot-reload watcher started".to_string()),
+        )
+        .await;
+    let mut config_rx_api_bridge = config_rx.clone();
+    let api_config_tx_bridge = api_config_tx.clone();
+    tokio::spawn(async move {
+        loop {
+            if config_rx_api_bridge.changed().await.is_err() {
+                break;
+            }
+            let cfg = config_rx_api_bridge.borrow_and_update().clone();
+            api_config_tx_bridge.send_replace(cfg);
+        }
+    });
+
+    let stats_policy = stats.clone();
+    let mut config_rx_policy = config_rx.clone();
+    tokio::spawn(async move {
+        loop {
+            if config_rx_policy.changed().await.is_err() {
+                break;
+            }
+            let cfg = config_rx_policy.borrow_and_update().clone();
+            stats_policy.apply_telemetry_policy(TelemetryPolicy::from_config(&cfg.general.telemetry));
+            if let Some(pool) = &me_pool_for_policy {
+                pool.update_runtime_transport_policy(
+                    cfg.general.me_socks_kdf_policy,
+                    cfg.general.me_route_backpressure_base_timeout_ms,
+                    cfg.general.me_route_backpressure_high_timeout_ms,
+                    cfg.general.me_route_backpressure_high_watermark_pct,
+                    cfg.general.me_reader_route_data_wait_ms,
+                );
+            }
+        }
+    });
+
+    let ip_tracker_policy = ip_tracker.clone();
+    let mut config_rx_ip_limits = config_rx.clone();
+    tokio::spawn(async move {
+        let mut prev_limits = config_rx_ip_limits.borrow().access.user_max_unique_ips.clone();
+        let mut prev_global_each = config_rx_ip_limits
+            .borrow()
+            .access
+            .user_max_unique_ips_global_each;
+        let mut prev_mode = config_rx_ip_limits.borrow().access.user_max_unique_ips_mode;
+        let mut prev_window = config_rx_ip_limits
+            .borrow()
+            .access
+            .user_max_unique_ips_window_secs;
+
+        loop {
+            if config_rx_ip_limits.changed().await.is_err() {
+                break;
+            }
+            let cfg = config_rx_ip_limits.borrow_and_update().clone();
+
+            if prev_limits != cfg.access.user_max_unique_ips
+                || prev_global_each != cfg.access.user_max_unique_ips_global_each
+            {
+                ip_tracker_policy
+                    .load_limits(
+                        cfg.access.user_max_unique_ips_global_each,
+                        &cfg.access.user_max_unique_ips,
+                    )
+                    .await;
+                prev_limits = cfg.access.user_max_unique_ips.clone();
+                prev_global_each = cfg.access.user_max_unique_ips_global_each;
+            }
+
+            if prev_mode != cfg.access.user_max_unique_ips_mode
+                || prev_window != cfg.access.user_max_unique_ips_window_secs
+            {
+                ip_tracker_policy
+                    .set_limit_policy(
+                        cfg.access.user_max_unique_ips_mode,
+                        cfg.access.user_max_unique_ips_window_secs,
+                    )
+                    .await;
+                prev_mode = cfg.access.user_max_unique_ips_mode;
+                prev_window = cfg.access.user_max_unique_ips_window_secs;
+            }
+        }
+    });
+
+    let beobachten_writer = beobachten.clone();
+    let config_rx_beobachten = config_rx.clone();
+    tokio::spawn(async move {
+        loop {
+            let cfg = config_rx_beobachten.borrow().clone();
+            let sleep_secs = cfg.general.beobachten_flush_secs.max(1);
+
+            if cfg.general.beobachten {
+                let ttl = std::time::Duration::from_secs(cfg.general.beobachten_minutes.saturating_mul(60));
+                let path = cfg.general.beobachten_file.clone();
+                let snapshot = beobachten_writer.snapshot_text(ttl);
+                if let Err(e) = write_beobachten_snapshot(&path, &snapshot).await {
+                    warn!(error = %e, path = %path, "Failed to flush beobachten snapshot");
+                }
+            }
+
+            tokio::time::sleep(std::time::Duration::from_secs(sleep_secs)).await;
+        }
+    });
+
+    if let Some(pool) = me_pool {
+        let reinit_trigger_capacity = config.general.me_reinit_trigger_channel.max(1);
+        let (reinit_tx, reinit_rx) = mpsc::channel::<MeReinitTrigger>(reinit_trigger_capacity);
+
+        let pool_clone_sched = pool.clone();
+        let rng_clone_sched = rng.clone();
+        let config_rx_clone_sched = config_rx.clone();
+        tokio::spawn(async move {
+            crate::transport::middle_proxy::me_reinit_scheduler(
+                pool_clone_sched,
+                rng_clone_sched,
+                config_rx_clone_sched,
+                reinit_rx,
+            )
+            .await;
+        });
+
+        let pool_clone = pool.clone();
+        let config_rx_clone = config_rx.clone();
+        let reinit_tx_updater = reinit_tx.clone();
+        tokio::spawn(async move {
+            crate::transport::middle_proxy::me_config_updater(
+                pool_clone,
+                config_rx_clone,
+                reinit_tx_updater,
+            )
+            .await;
+        });
+
+        let config_rx_clone_rot = config_rx.clone();
+        let reinit_tx_rotation = reinit_tx.clone();
+        tokio::spawn(async move {
+            crate::transport::middle_proxy::me_rotation_task(config_rx_clone_rot, reinit_tx_rotation)
+                .await;
+        });
+    }
+
+    RuntimeWatches {
+        config_rx,
+        log_level_rx,
+        detected_ip_v4,
+        detected_ip_v6,
+    }
+}
+
+pub(crate) async fn apply_runtime_log_filter(
+    has_rust_log: bool,
+    effective_log_level: &LogLevel,
+    filter_handle: reload::Handle<EnvFilter, tracing_subscriber::Registry>,
+    mut log_level_rx: watch::Receiver<LogLevel>,
+) {
+    let runtime_filter = if has_rust_log {
+        EnvFilter::from_default_env()
+    } else if matches!(effective_log_level, LogLevel::Silent) {
+        EnvFilter::new("warn,telemt::links=info")
+    } else {
+        EnvFilter::new(effective_log_level.to_filter_str())
+    };
+    filter_handle
+        .reload(runtime_filter)
+        .expect("Failed to switch log filter");
+
+    tokio::spawn(async move {
+        loop {
+            if log_level_rx.changed().await.is_err() {
+                break;
+            }
+            let level = log_level_rx.borrow_and_update().clone();
+            let new_filter = tracing_subscriber::EnvFilter::new(level.to_filter_str());
+            if let Err(e) = filter_handle.reload(new_filter) {
+                tracing::error!("config reload: failed to update log filter: {}", e);
+            }
+        }
+    });
+}
+
+pub(crate) async fn spawn_metrics_if_configured(
+    config: &Arc<ProxyConfig>,
+    startup_tracker: &Arc<StartupTracker>,
+    stats: Arc<Stats>,
+    beobachten: Arc<BeobachtenStore>,
+    ip_tracker: Arc<UserIpTracker>,
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+) {
+    // metrics_listen takes precedence; fall back to metrics_port for backward compat.
+    let metrics_target: Option<(u16, Option<String>)> =
+        if let Some(ref listen) = config.server.metrics_listen {
+            match listen.parse::<std::net::SocketAddr>() {
+                Ok(addr) => Some((addr.port(), Some(listen.clone()))),
+                Err(e) => {
+                    startup_tracker
+                        .skip_component(
+                            COMPONENT_METRICS_START,
+                            Some(format!("invalid metrics_listen \"{}\": {}", listen, e)),
+                        )
+                        .await;
+                    None
+                }
+            }
+        } else {
+            config.server.metrics_port.map(|p| (p, None))
+        };
+
+    if let Some((port, listen)) = metrics_target {
+        let fallback_label = format!("port {}", port);
+        let label = listen.as_deref().unwrap_or(&fallback_label);
+        startup_tracker
+            .start_component(
+                COMPONENT_METRICS_START,
+                Some(format!("spawn metrics endpoint on {}", label)),
+            )
+            .await;
+        let stats = stats.clone();
+        let beobachten = beobachten.clone();
+        let config_rx_metrics = config_rx.clone();
+        let ip_tracker_metrics = ip_tracker.clone();
+        let whitelist = config.server.metrics_whitelist.clone();
+        tokio::spawn(async move {
+            metrics::serve(
+                port,
+                listen,
+                stats,
+                beobachten,
+                ip_tracker_metrics,
+                config_rx_metrics,
+                whitelist,
+            )
+            .await;
+        });
+        startup_tracker
+            .complete_component(
+                COMPONENT_METRICS_START,
+                Some("metrics task spawned".to_string()),
+            )
+            .await;
+    } else if config.server.metrics_listen.is_none() {
+        startup_tracker
+            .skip_component(
+                COMPONENT_METRICS_START,
+                Some("server.metrics_port is not configured".to_string()),
+            )
+            .await;
+    }
+}
+
+pub(crate) async fn mark_runtime_ready(startup_tracker: &Arc<StartupTracker>) {
+    startup_tracker
+        .complete_component(
+            COMPONENT_RUNTIME_READY,
+            Some("startup pipeline is fully initialized".to_string()),
+        )
+        .await;
+    startup_tracker.mark_ready().await;
+}

src/maestro/shutdown.rs

@@ -0,0 +1,42 @@
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use tokio::signal;
+use tracing::{error, info, warn};
+
+use crate::transport::middle_proxy::MePool;
+
+use super::helpers::{format_uptime, unit_label};
+
+pub(crate) async fn wait_for_shutdown(process_started_at: Instant, me_pool: Option<Arc<MePool>>) {
+    match signal::ctrl_c().await {
+        Ok(()) => {
+            let shutdown_started_at = Instant::now();
+            info!("Shutting down...");
+            let uptime_secs = process_started_at.elapsed().as_secs();
+            info!("Uptime: {}", format_uptime(uptime_secs));
+            if let Some(pool) = &me_pool {
+                match tokio::time::timeout(Duration::from_secs(2), pool.shutdown_send_close_conn_all())
+                    .await
+                {
+                    Ok(total) => {
+                        info!(
+                            close_conn_sent = total,
+                            "ME shutdown: RPC_CLOSE_CONN broadcast completed"
+                        );
+                    }
+                    Err(_) => {
+                        warn!("ME shutdown: RPC_CLOSE_CONN broadcast timed out");
+                    }
+                }
+            }
+            let shutdown_secs = shutdown_started_at.elapsed().as_secs();
+            info!(
+                "Shutdown completed successfully in {} {}.",
+                shutdown_secs,
+                unit_label(shutdown_secs, "second", "seconds")
+            );
+        }
+        Err(e) => error!("Signal error: {}", e),
+    }
+}

src/maestro/tls_bootstrap.rs

@@ -0,0 +1,165 @@
+use std::sync::Arc;
+use std::time::Duration;
+
+use rand::Rng;
+use tracing::warn;
+
+use crate::config::ProxyConfig;
+use crate::startup::{COMPONENT_TLS_FRONT_BOOTSTRAP, StartupTracker};
+use crate::tls_front::TlsFrontCache;
+use crate::transport::UpstreamManager;
+
+pub(crate) async fn bootstrap_tls_front(
+    config: &ProxyConfig,
+    tls_domains: &[String],
+    upstream_manager: Arc<UpstreamManager>,
+    startup_tracker: &Arc<StartupTracker>,
+) -> Option<Arc<TlsFrontCache>> {
+    startup_tracker
+        .start_component(
+            COMPONENT_TLS_FRONT_BOOTSTRAP,
+            Some("initialize TLS front cache/bootstrap tasks".to_string()),
+        )
+        .await;
+
+    let tls_cache: Option<Arc<TlsFrontCache>> = if config.censorship.tls_emulation {
+        let cache = Arc::new(TlsFrontCache::new(
+            tls_domains,
+            config.censorship.fake_cert_len,
+            &config.censorship.tls_front_dir,
+        ));
+        cache.load_from_disk().await;
+
+        let port = config.censorship.mask_port;
+        let proxy_protocol = config.censorship.mask_proxy_protocol;
+        let mask_host = config
+            .censorship
+            .mask_host
+            .clone()
+            .unwrap_or_else(|| config.censorship.tls_domain.clone());
+        let mask_unix_sock = config.censorship.mask_unix_sock.clone();
+        let fetch_timeout = Duration::from_secs(5);
+
+        let cache_initial = cache.clone();
+        let domains_initial = tls_domains.to_vec();
+        let host_initial = mask_host.clone();
+        let unix_sock_initial = mask_unix_sock.clone();
+        let upstream_initial = upstream_manager.clone();
+        tokio::spawn(async move {
+            let mut join = tokio::task::JoinSet::new();
+            for domain in domains_initial {
+                let cache_domain = cache_initial.clone();
+                let host_domain = host_initial.clone();
+                let unix_sock_domain = unix_sock_initial.clone();
+                let upstream_domain = upstream_initial.clone();
+                join.spawn(async move {
+                    match crate::tls_front::fetcher::fetch_real_tls(
+                        &host_domain,
+                        port,
+                        &domain,
+                        fetch_timeout,
+                        Some(upstream_domain),
+                        proxy_protocol,
+                        unix_sock_domain.as_deref(),
+                    )
+                    .await
+                    {
+                        Ok(res) => cache_domain.update_from_fetch(&domain, res).await,
+                        Err(e) => {
+                            warn!(domain = %domain, error = %e, "TLS emulation initial fetch failed")
+                        }
+                    }
+                });
+            }
+            while let Some(res) = join.join_next().await {
+                if let Err(e) = res {
+                    warn!(error = %e, "TLS emulation initial fetch task join failed");
+                }
+            }
+        });
+
+        let cache_timeout = cache.clone();
+        let domains_timeout = tls_domains.to_vec();
+        let fake_cert_len = config.censorship.fake_cert_len;
+        tokio::spawn(async move {
+            tokio::time::sleep(fetch_timeout).await;
+            for domain in domains_timeout {
+                let cached = cache_timeout.get(&domain).await;
+                if cached.domain == "default" {
+                    warn!(
+                        domain = %domain,
+                        timeout_secs = fetch_timeout.as_secs(),
+                        fake_cert_len,
+                        "TLS-front fetch not ready within timeout; using cache/default fake cert fallback"
+                    );
+                }
+            }
+        });
+
+        let cache_refresh = cache.clone();
+        let domains_refresh = tls_domains.to_vec();
+        let host_refresh = mask_host.clone();
+        let unix_sock_refresh = mask_unix_sock.clone();
+        let upstream_refresh = upstream_manager.clone();
+        tokio::spawn(async move {
+            loop {
+                let base_secs = rand::rng().random_range(4 * 3600..=6 * 3600);
+                let jitter_secs = rand::rng().random_range(0..=7200);
+                tokio::time::sleep(Duration::from_secs(base_secs + jitter_secs)).await;
+
+                let mut join = tokio::task::JoinSet::new();
+                for domain in domains_refresh.clone() {
+                    let cache_domain = cache_refresh.clone();
+                    let host_domain = host_refresh.clone();
+                    let unix_sock_domain = unix_sock_refresh.clone();
+                    let upstream_domain = upstream_refresh.clone();
+                    join.spawn(async move {
+                        match crate::tls_front::fetcher::fetch_real_tls(
+                            &host_domain,
+                            port,
+                            &domain,
+                            fetch_timeout,
+                            Some(upstream_domain),
+                            proxy_protocol,
+                            unix_sock_domain.as_deref(),
+                        )
+                        .await
+                        {
+                            Ok(res) => cache_domain.update_from_fetch(&domain, res).await,
+                            Err(e) => {
+                                warn!(domain = %domain, error = %e, "TLS emulation refresh failed")
+                            }
+                        }
+                    });
+                }
+
+                while let Some(res) = join.join_next().await {
+                    if let Err(e) = res {
+                        warn!(error = %e, "TLS emulation refresh task join failed");
+                    }
+                }
+            }
+        });
+
+        Some(cache)
+    } else {
+        startup_tracker
+            .skip_component(
+                COMPONENT_TLS_FRONT_BOOTSTRAP,
+                Some("censorship.tls_emulation is false".to_string()),
+            )
+            .await;
+        None
+    };
+
+    if tls_cache.is_some() {
+        startup_tracker
+            .complete_component(
+                COMPONENT_TLS_FRONT_BOOTSTRAP,
+                Some("tls front cache is initialized".to_string()),
+            )
+            .await;
+    }
+
+    tls_cache
+}

src/metrics.rs

@@ -17,25 +17,128 @@ use crate::config::ProxyConfig;
 use crate::ip_tracker::UserIpTracker;
 use crate::stats::beobachten::BeobachtenStore;
 use crate::stats::Stats;
+use crate::transport::{ListenOptions, create_listener};
 
 pub async fn serve(
     port: u16,
+    listen: Option<String>,
     stats: Arc<Stats>,
     beobachten: Arc<BeobachtenStore>,
     ip_tracker: Arc<UserIpTracker>,
     config_rx: tokio::sync::watch::Receiver<Arc<ProxyConfig>>,
     whitelist: Vec<IpNetwork>,
 ) {
-    let addr = SocketAddr::from(([0, 0, 0, 0], port));
-    let listener = match TcpListener::bind(addr).await {
-        Ok(l) => l,
-        Err(e) => {
-            warn!(error = %e, "Failed to bind metrics on {}", addr);
-            return;
-        }
-    };
-    info!("Metrics endpoint: http://{}/metrics and /beobachten", addr);
+    let whitelist = Arc::new(whitelist);
 
+    // If `metrics_listen` is set, bind on that single address only.
+    if let Some(ref listen_addr) = listen {
+        let addr: SocketAddr = match listen_addr.parse() {
+            Ok(a) => a,
+            Err(e) => {
+                warn!(error = %e, "Invalid metrics_listen address: {}", listen_addr);
+                return;
+            }
+        };
+        let is_ipv6 = addr.is_ipv6();
+        match bind_metrics_listener(addr, is_ipv6) {
+            Ok(listener) => {
+                info!("Metrics endpoint: http://{}/metrics and /beobachten", addr);
+                serve_listener(
+                    listener, stats, beobachten, ip_tracker, config_rx, whitelist,
+                )
+                .await;
+            }
+            Err(e) => {
+                warn!(error = %e, "Failed to bind metrics on {}", addr);
+            }
+        }
+        return;
+    }
+
+    // Fallback: bind on 0.0.0.0 and [::] using metrics_port.
+    let mut listener_v4 = None;
+    let mut listener_v6 = None;
+
+    let addr_v4 = SocketAddr::from(([0, 0, 0, 0], port));
+    match bind_metrics_listener(addr_v4, false) {
+        Ok(listener) => {
+            info!("Metrics endpoint: http://{}/metrics and /beobachten", addr_v4);
+            listener_v4 = Some(listener);
+        }
+        Err(e) => {
+            warn!(error = %e, "Failed to bind metrics on {}", addr_v4);
+        }
+    }
+
+    let addr_v6 = SocketAddr::from(([0, 0, 0, 0, 0, 0, 0, 0], port));
+    match bind_metrics_listener(addr_v6, true) {
+        Ok(listener) => {
+            info!("Metrics endpoint: http://[::]:{}/metrics and /beobachten", port);
+            listener_v6 = Some(listener);
+        }
+        Err(e) => {
+            warn!(error = %e, "Failed to bind metrics on {}", addr_v6);
+        }
+    }
+
+    match (listener_v4, listener_v6) {
+        (None, None) => {
+            warn!("Metrics listener is unavailable on both IPv4 and IPv6");
+        }
+        (Some(listener), None) | (None, Some(listener)) => {
+            serve_listener(
+                listener, stats, beobachten, ip_tracker, config_rx, whitelist,
+            )
+            .await;
+        }
+        (Some(listener4), Some(listener6)) => {
+            let stats_v6 = stats.clone();
+            let beobachten_v6 = beobachten.clone();
+            let ip_tracker_v6 = ip_tracker.clone();
+            let config_rx_v6 = config_rx.clone();
+            let whitelist_v6 = whitelist.clone();
+            tokio::spawn(async move {
+                serve_listener(
+                    listener6,
+                    stats_v6,
+                    beobachten_v6,
+                    ip_tracker_v6,
+                    config_rx_v6,
+                    whitelist_v6,
+                )
+                .await;
+            });
+            serve_listener(
+                listener4,
+                stats,
+                beobachten,
+                ip_tracker,
+                config_rx,
+                whitelist,
+            )
+            .await;
+        }
+    }
+}
+
+fn bind_metrics_listener(addr: SocketAddr, ipv6_only: bool) -> std::io::Result<TcpListener> {
+    let options = ListenOptions {
+        reuse_port: false,
+        ipv6_only,
+        ..Default::default()
+    };
+    let socket = create_listener(addr, &options)?;
+    TcpListener::from_std(socket.into())
+}
+
+async fn serve_listener(
+    listener: TcpListener,
+    stats: Arc<Stats>,
+    beobachten: Arc<BeobachtenStore>,
+    ip_tracker: Arc<UserIpTracker>,
+    config_rx: tokio::sync::watch::Receiver<Arc<ProxyConfig>>,
+    whitelist: Arc<Vec<IpNetwork>>,
+) {
     loop {
         let (stream, peer) = match listener.accept().await {
             Ok(v) => v,
@@ -689,6 +792,135 @@ async fn render_metrics(stats: &Stats, config: &ProxyConfig, ip_tracker: &UserIp
         }
     );
 
+    let _ = writeln!(
+        out,
+        "# HELP telemt_me_writer_pick_total ME writer-pick outcomes by mode and result"
+    );
+    let _ = writeln!(out, "# TYPE telemt_me_writer_pick_total counter");
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_pick_total{{mode=\"sorted_rr\",result=\"success_try\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_pick_sorted_rr_success_try_total()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_pick_total{{mode=\"sorted_rr\",result=\"success_fallback\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_pick_sorted_rr_success_fallback_total()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_pick_total{{mode=\"sorted_rr\",result=\"full\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_pick_sorted_rr_full_total()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_pick_total{{mode=\"sorted_rr\",result=\"closed\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_pick_sorted_rr_closed_total()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_pick_total{{mode=\"sorted_rr\",result=\"no_candidate\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_pick_sorted_rr_no_candidate_total()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_pick_total{{mode=\"p2c\",result=\"success_try\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_pick_p2c_success_try_total()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_pick_total{{mode=\"p2c\",result=\"success_fallback\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_pick_p2c_success_fallback_total()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_pick_total{{mode=\"p2c\",result=\"full\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_pick_p2c_full_total()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_pick_total{{mode=\"p2c\",result=\"closed\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_pick_p2c_closed_total()
+        } else {
+            0
+        }
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_pick_total{{mode=\"p2c\",result=\"no_candidate\"}} {}",
+        if me_allows_normal {
+            stats.get_me_writer_pick_p2c_no_candidate_total()
+        } else {
+            0
+        }
+    );
+
+    let _ = writeln!(
+        out,
+        "# HELP telemt_me_writer_pick_blocking_fallback_total ME writer-pick blocking fallback attempts"
+    );
+    let _ = writeln!(
+        out,
+        "# TYPE telemt_me_writer_pick_blocking_fallback_total counter"
+    );
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_pick_blocking_fallback_total {}",
+        if me_allows_normal {
+            stats.get_me_writer_pick_blocking_fallback_total()
+        } else {
+            0
+        }
+    );
+
+    let _ = writeln!(
+        out,
+        "# HELP telemt_me_writer_pick_mode_switch_total Writer-pick mode switches via runtime updates"
+    );
+    let _ = writeln!(out, "# TYPE telemt_me_writer_pick_mode_switch_total counter");
+    let _ = writeln!(
+        out,
+        "telemt_me_writer_pick_mode_switch_total {}",
+        if me_allows_normal {
+            stats.get_me_writer_pick_mode_switch_total()
+        } else {
+            0
+        }
+    );
+
     let _ = writeln!(
         out,
         "# HELP telemt_me_socks_kdf_policy_total SOCKS KDF policy outcomes"
@@ -1570,14 +1802,24 @@ async fn render_metrics(stats: &Stats, config: &ProxyConfig, ip_tracker: &UserIp
             "# HELP telemt_user_unique_ips_recent_window Per-user unique IPs seen in configured observation window"
         );
         let _ = writeln!(out, "# TYPE telemt_user_unique_ips_recent_window gauge");
-        let _ = writeln!(out, "# HELP telemt_user_unique_ips_limit Per-user configured unique IP limit (0 means unlimited)");
+        let _ = writeln!(out, "# HELP telemt_user_unique_ips_limit Effective per-user unique IP limit (0 means unlimited)");
         let _ = writeln!(out, "# TYPE telemt_user_unique_ips_limit gauge");
         let _ = writeln!(out, "# HELP telemt_user_unique_ips_utilization Per-user unique IP usage ratio (0 for unlimited)");
         let _ = writeln!(out, "# TYPE telemt_user_unique_ips_utilization gauge");
 
         for user in unique_users {
             let current = ip_counts.get(&user).copied().unwrap_or(0);
-            let limit = config.access.user_max_unique_ips.get(&user).copied().unwrap_or(0);
+            let limit = config
+                .access
+                .user_max_unique_ips
+                .get(&user)
+                .copied()
+                .filter(|limit| *limit > 0)
+                .or(
+                    (config.access.user_max_unique_ips_global_each > 0)
+                        .then_some(config.access.user_max_unique_ips_global_each),
+                )
+                .unwrap_or(0);
             let utilization = if limit > 0 {
                 current as f64 / limit as f64
             } else {
@@ -1700,6 +1942,25 @@ mod tests {
         assert!(output.contains("telemt_user_unique_ips_recent_window{user="));
     }
 
+    #[tokio::test]
+    async fn test_render_uses_global_each_unique_ip_limit() {
+        let stats = Stats::new();
+        stats.increment_user_connects("alice");
+        stats.increment_user_curr_connects("alice");
+        let tracker = UserIpTracker::new();
+        tracker
+            .check_and_add("alice", "203.0.113.10".parse().unwrap())
+            .await
+            .unwrap();
+        let mut config = ProxyConfig::default();
+        config.access.user_max_unique_ips_global_each = 2;
+
+        let output = render_metrics(&stats, &config, &tracker).await;
+
+        assert!(output.contains("telemt_user_unique_ips_limit{user=\"alice\"} 2"));
+        assert!(output.contains("telemt_user_unique_ips_utilization{user=\"alice\"} 0.500000"));
+    }
+
     #[tokio::test]
     async fn test_render_has_type_annotations() {
         let stats = Stats::new();

src/network/probe.rs

@@ -8,9 +8,10 @@ use tokio::task::JoinSet;
 use tokio::time::timeout;
 use tracing::{debug, info, warn};
 
-use crate::config::NetworkConfig;
+use crate::config::{NetworkConfig, UpstreamConfig, UpstreamType};
 use crate::error::Result;
-use crate::network::stun::{stun_probe_dual, DualStunResult, IpFamily, StunProbeResult};
+use crate::network::stun::{stun_probe_family_with_bind, DualStunResult, IpFamily, StunProbeResult};
+use crate::transport::UpstreamManager;
 
 #[derive(Debug, Clone, Default)]
 pub struct NetworkProbe {
@@ -57,19 +58,22 @@ const STUN_BATCH_TIMEOUT: Duration = Duration::from_secs(5);
 
 pub async fn run_probe(
     config: &NetworkConfig,
+    upstreams: &[UpstreamConfig],
     nat_probe: bool,
     stun_nat_probe_concurrency: usize,
 ) -> Result<NetworkProbe> {
     let mut probe = NetworkProbe::default();
+    let servers = collect_stun_servers(config);
+    let mut detected_ipv4 = detect_local_ip_v4();
+    let mut detected_ipv6 = detect_local_ip_v6();
+    let mut explicit_detected_ipv4 = false;
+    let mut explicit_detected_ipv6 = false;
+    let mut explicit_reflected_ipv4 = false;
+    let mut explicit_reflected_ipv6 = false;
+    let mut strict_bind_ipv4_requested = false;
+    let mut strict_bind_ipv6_requested = false;
 
-    probe.detected_ipv4 = detect_local_ip_v4();
-    probe.detected_ipv6 = detect_local_ip_v6();
-
-    probe.ipv4_is_bogon = probe.detected_ipv4.map(is_bogon_v4).unwrap_or(false);
-    probe.ipv6_is_bogon = probe.detected_ipv6.map(is_bogon_v6).unwrap_or(false);
-
-    let stun_res = if nat_probe && config.stun_use {
-        let servers = collect_stun_servers(config);
+    let global_stun_res = if nat_probe && config.stun_use {
         if servers.is_empty() {
             warn!("STUN probe is enabled but network.stun_servers is empty");
             DualStunResult::default()
@@ -77,6 +81,8 @@ pub async fn run_probe(
             probe_stun_servers_parallel(
                 &servers,
                 stun_nat_probe_concurrency.max(1),
+                None,
+                None,
             )
             .await
         }
@@ -86,8 +92,108 @@ pub async fn run_probe(
     } else {
         DualStunResult::default()
     };
-    probe.reflected_ipv4 = stun_res.v4.map(|r| r.reflected_addr);
-    probe.reflected_ipv6 = stun_res.v6.map(|r| r.reflected_addr);
+    let mut reflected_ipv4 = global_stun_res.v4.map(|r| r.reflected_addr);
+    let mut reflected_ipv6 = global_stun_res.v6.map(|r| r.reflected_addr);
+
+    for upstream in upstreams.iter().filter(|upstream| upstream.enabled) {
+        let UpstreamType::Direct {
+            interface,
+            bind_addresses,
+        } = &upstream.upstream_type else {
+            continue;
+        };
+        if let Some(addrs) = bind_addresses.as_ref().filter(|v| !v.is_empty()) {
+            let mut saw_parsed_ip = false;
+            for value in addrs {
+                if let Ok(ip) = value.parse::<IpAddr>() {
+                    saw_parsed_ip = true;
+                    if ip.is_ipv4() {
+                        strict_bind_ipv4_requested = true;
+                    } else {
+                        strict_bind_ipv6_requested = true;
+                    }
+                }
+            }
+            if !saw_parsed_ip {
+                strict_bind_ipv4_requested = true;
+                strict_bind_ipv6_requested = true;
+            }
+        }
+
+        let bind_v4 = UpstreamManager::resolve_bind_address(
+            interface,
+            bind_addresses,
+            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(198, 51, 100, 1)), 443),
+            None,
+            true,
+        );
+        let bind_v6 = UpstreamManager::resolve_bind_address(
+            interface,
+            bind_addresses,
+            SocketAddr::new(
+                IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1)),
+                443,
+            ),
+            None,
+            true,
+        );
+
+        if let Some(IpAddr::V4(ip)) = bind_v4
+            && !explicit_detected_ipv4
+        {
+            detected_ipv4 = Some(ip);
+            explicit_detected_ipv4 = true;
+        }
+        if let Some(IpAddr::V6(ip)) = bind_v6
+            && !explicit_detected_ipv6
+        {
+            detected_ipv6 = Some(ip);
+            explicit_detected_ipv6 = true;
+        }
+        if bind_v4.is_none() && bind_v6.is_none() {
+            continue;
+        }
+
+        if !(nat_probe && config.stun_use) || servers.is_empty() {
+            continue;
+        }
+
+        let direct_stun_res = probe_stun_servers_parallel(
+            &servers,
+            stun_nat_probe_concurrency.max(1),
+            bind_v4,
+            bind_v6,
+        )
+        .await;
+        if let Some(reflected) = direct_stun_res.v4.map(|r| r.reflected_addr) {
+            reflected_ipv4 = Some(reflected);
+            explicit_reflected_ipv4 = true;
+        }
+        if let Some(reflected) = direct_stun_res.v6.map(|r| r.reflected_addr) {
+            reflected_ipv6 = Some(reflected);
+            explicit_reflected_ipv6 = true;
+        }
+    }
+
+    if strict_bind_ipv4_requested && !explicit_detected_ipv4 {
+        detected_ipv4 = None;
+        reflected_ipv4 = None;
+    } else if strict_bind_ipv4_requested && !explicit_reflected_ipv4 {
+        reflected_ipv4 = None;
+    }
+    if strict_bind_ipv6_requested && !explicit_detected_ipv6 {
+        detected_ipv6 = None;
+        reflected_ipv6 = None;
+    } else if strict_bind_ipv6_requested && !explicit_reflected_ipv6 {
+        reflected_ipv6 = None;
+    }
+
+    probe.detected_ipv4 = detected_ipv4;
+    probe.detected_ipv6 = detected_ipv6;
+    probe.reflected_ipv4 = reflected_ipv4;
+    probe.reflected_ipv6 = reflected_ipv6;
+    probe.ipv4_is_bogon = probe.detected_ipv4.map(is_bogon_v4).unwrap_or(false);
+    probe.ipv6_is_bogon = probe.detected_ipv6.map(is_bogon_v6).unwrap_or(false);
 
     // If STUN is blocked but IPv4 is private, try HTTP public-IP fallback.
     if nat_probe
@@ -162,6 +268,8 @@ fn collect_stun_servers(config: &NetworkConfig) -> Vec<String> {
 async fn probe_stun_servers_parallel(
     servers: &[String],
     concurrency: usize,
+    bind_v4: Option<IpAddr>,
+    bind_v6: Option<IpAddr>,
 ) -> DualStunResult {
     let mut join_set = JoinSet::new();
     let mut next_idx = 0usize;
@@ -172,8 +280,15 @@ async fn probe_stun_servers_parallel(
         while next_idx < servers.len() && join_set.len() < concurrency {
             let stun_addr = servers[next_idx].clone();
             next_idx += 1;
+            let bind_v4 = bind_v4;
+            let bind_v6 = bind_v6;
             join_set.spawn(async move {
-                let res = timeout(STUN_BATCH_TIMEOUT, stun_probe_dual(&stun_addr)).await;
+                let res = timeout(STUN_BATCH_TIMEOUT, async {
+                    let v4 = stun_probe_family_with_bind(&stun_addr, IpFamily::V4, bind_v4).await?;
+                    let v6 = stun_probe_family_with_bind(&stun_addr, IpFamily::V6, bind_v6).await?;
+                    Ok::<DualStunResult, crate::error::ProxyError>(DualStunResult { v4, v6 })
+                })
+                .await;
                 (stun_addr, res)
             });
         }
@@ -226,18 +341,24 @@ async fn probe_stun_servers_parallel(
     out
 }
 
-pub fn decide_network_capabilities(config: &NetworkConfig, probe: &NetworkProbe) -> NetworkDecision {
+pub fn decide_network_capabilities(
+    config: &NetworkConfig,
+    probe: &NetworkProbe,
+    middle_proxy_nat_ip: Option<IpAddr>,
+) -> NetworkDecision {
     let ipv4_dc = config.ipv4 && probe.detected_ipv4.is_some();
     let ipv6_dc = config.ipv6.unwrap_or(probe.detected_ipv6.is_some()) && probe.detected_ipv6.is_some();
+    let nat_ip_v4 = matches!(middle_proxy_nat_ip, Some(IpAddr::V4(_)));
+    let nat_ip_v6 = matches!(middle_proxy_nat_ip, Some(IpAddr::V6(_)));
 
     let ipv4_me = config.ipv4
         && probe.detected_ipv4.is_some()
-        && (!probe.ipv4_is_bogon || probe.reflected_ipv4.is_some());
+        && (!probe.ipv4_is_bogon || probe.reflected_ipv4.is_some() || nat_ip_v4);
 
     let ipv6_enabled = config.ipv6.unwrap_or(probe.detected_ipv6.is_some());
     let ipv6_me = ipv6_enabled
         && probe.detected_ipv6.is_some()
-        && (!probe.ipv6_is_bogon || probe.reflected_ipv6.is_some());
+        && (!probe.ipv6_is_bogon || probe.reflected_ipv6.is_some() || nat_ip_v6);
 
     let effective_prefer = match config.prefer {
         6 if ipv6_me || ipv6_dc => 6,
@@ -262,6 +383,58 @@ pub fn decide_network_capabilities(config: &NetworkConfig, probe: &NetworkProbe)
     }
 }
 
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::NetworkConfig;
+
+    #[test]
+    fn manual_nat_ip_enables_ipv4_me_without_reflection() {
+        let config = NetworkConfig {
+            ipv4: true,
+            ..Default::default()
+        };
+        let probe = NetworkProbe {
+            detected_ipv4: Some(Ipv4Addr::new(10, 0, 0, 10)),
+            ipv4_is_bogon: true,
+            ..Default::default()
+        };
+
+        let decision = decide_network_capabilities(
+            &config,
+            &probe,
+            Some(IpAddr::V4(Ipv4Addr::new(1, 2, 3, 4))),
+        );
+
+        assert!(decision.ipv4_me);
+    }
+
+    #[test]
+    fn manual_nat_ip_does_not_enable_other_family() {
+        let config = NetworkConfig {
+            ipv4: true,
+            ipv6: Some(true),
+            ..Default::default()
+        };
+        let probe = NetworkProbe {
+            detected_ipv4: Some(Ipv4Addr::new(10, 0, 0, 10)),
+            detected_ipv6: Some(Ipv6Addr::LOCALHOST),
+            ipv4_is_bogon: true,
+            ipv6_is_bogon: true,
+            ..Default::default()
+        };
+
+        let decision = decide_network_capabilities(
+            &config,
+            &probe,
+            Some(IpAddr::V4(Ipv4Addr::new(1, 2, 3, 4))),
+        );
+
+        assert!(decision.ipv4_me);
+        assert!(!decision.ipv6_me);
+    }
+}
+
 fn detect_local_ip_v4() -> Option<Ipv4Addr> {
     let socket = UdpSocket::bind("0.0.0.0:0").ok()?;
     socket.connect("8.8.8.8:80").ok()?;
@@ -280,6 +453,14 @@ fn detect_local_ip_v6() -> Option<Ipv6Addr> {
     }
 }
 
+pub fn detect_interface_ipv4() -> Option<Ipv4Addr> {
+    detect_local_ip_v4()
+}
+
+pub fn detect_interface_ipv6() -> Option<Ipv6Addr> {
+    detect_local_ip_v6()
+}
+
 pub fn is_bogon(ip: IpAddr) -> bool {
     match ip {
         IpAddr::V4(v4) => is_bogon_v4(v4),

src/proxy/client.rs

@@ -39,6 +39,7 @@ use crate::proxy::direct_relay::handle_via_direct;
 use crate::proxy::handshake::{HandshakeSuccess, handle_mtproto_handshake, handle_tls_handshake};
 use crate::proxy::masking::handle_bad_client;
 use crate::proxy::middle_relay::handle_via_middle_proxy;
+use crate::proxy::route_mode::{RelayRouteMode, RouteRuntimeController};
 
 fn beobachten_ttl(config: &ProxyConfig) -> Duration {
     Duration::from_secs(config.general.beobachten_minutes.saturating_mul(60))
@@ -80,6 +81,7 @@ pub async fn handle_client_stream<S>(
     buffer_pool: Arc<BufferPool>,
     rng: Arc<SecureRandom>,
     me_pool: Option<Arc<MePool>>,
+    route_runtime: Arc<RouteRuntimeController>,
     tls_cache: Option<Arc<TlsFrontCache>>,
     ip_tracker: Arc<UserIpTracker>,
     beobachten: Arc<BeobachtenStore>,
@@ -214,6 +216,7 @@ where
                 RunningClientHandler::handle_authenticated_static(
                     crypto_reader, crypto_writer, success,
                     upstream_manager, stats, config, buffer_pool, rng, me_pool,
+                    route_runtime.clone(),
                     local_addr, real_peer, ip_tracker.clone(),
                 ),
             )))
@@ -274,6 +277,7 @@ where
                     buffer_pool,
                     rng,
                     me_pool,
+                    route_runtime.clone(),
                     local_addr,
                     real_peer,
                     ip_tracker.clone(),
@@ -317,6 +321,8 @@ pub struct ClientHandler;
 pub struct RunningClientHandler {
     stream: TcpStream,
     peer: SocketAddr,
+    real_peer_from_proxy: Option<SocketAddr>,
+    real_peer_report: Arc<std::sync::Mutex<Option<SocketAddr>>>,
     config: Arc<ProxyConfig>,
     stats: Arc<Stats>,
     replay_checker: Arc<ReplayChecker>,
@@ -324,6 +330,7 @@ pub struct RunningClientHandler {
     buffer_pool: Arc<BufferPool>,
     rng: Arc<SecureRandom>,
     me_pool: Option<Arc<MePool>>,
+    route_runtime: Arc<RouteRuntimeController>,
     tls_cache: Option<Arc<TlsFrontCache>>,
     ip_tracker: Arc<UserIpTracker>,
     beobachten: Arc<BeobachtenStore>,
@@ -341,14 +348,19 @@ impl ClientHandler {
         buffer_pool: Arc<BufferPool>,
         rng: Arc<SecureRandom>,
         me_pool: Option<Arc<MePool>>,
+        route_runtime: Arc<RouteRuntimeController>,
         tls_cache: Option<Arc<TlsFrontCache>>,
         ip_tracker: Arc<UserIpTracker>,
         beobachten: Arc<BeobachtenStore>,
         proxy_protocol_enabled: bool,
+        real_peer_report: Arc<std::sync::Mutex<Option<SocketAddr>>>,
     ) -> RunningClientHandler {
+        let normalized_peer = normalize_ip(peer);
         RunningClientHandler {
             stream,
-            peer,
+            peer: normalized_peer,
+            real_peer_from_proxy: None,
+            real_peer_report,
             config,
             stats,
             replay_checker,
@@ -356,6 +368,7 @@ impl ClientHandler {
             buffer_pool,
             rng,
             me_pool,
+            route_runtime,
             tls_cache,
             ip_tracker,
             beobachten,
@@ -365,10 +378,8 @@ impl ClientHandler {
 }
 
 impl RunningClientHandler {
-    pub async fn run(mut self) -> Result<()> {
+    pub async fn run(self) -> Result<()> {
         self.stats.increment_connects_all();
-
-        self.peer = normalize_ip(self.peer);
         let peer = self.peer;
         let _ip_tracker = self.ip_tracker.clone();
         debug!(peer = %peer, "New connection");
@@ -441,6 +452,10 @@ impl RunningClientHandler {
                         "PROXY protocol header parsed"
                     );
                     self.peer = normalize_ip(info.src_addr);
+                    self.real_peer_from_proxy = Some(self.peer);
+                    if let Ok(mut slot) = self.real_peer_report.lock() {
+                        *slot = Some(self.peer);
+                    }
                     if let Some(dst) = info.dst_addr {
                         local_addr = dst;
                     }
@@ -597,6 +612,7 @@ impl RunningClientHandler {
                 buffer_pool,
                 self.rng,
                 self.me_pool,
+                self.route_runtime.clone(),
                 local_addr,
                 peer,
                 self.ip_tracker,
@@ -677,6 +693,7 @@ impl RunningClientHandler {
                 buffer_pool,
                 self.rng,
                 self.me_pool,
+                self.route_runtime.clone(),
                 local_addr,
                 peer,
                 self.ip_tracker,
@@ -698,6 +715,7 @@ impl RunningClientHandler {
         buffer_pool: Arc<BufferPool>,
         rng: Arc<SecureRandom>,
         me_pool: Option<Arc<MePool>>,
+        route_runtime: Arc<RouteRuntimeController>,
         local_addr: SocketAddr,
         peer_addr: SocketAddr,
         ip_tracker: Arc<UserIpTracker>,
@@ -713,7 +731,11 @@ impl RunningClientHandler {
             return Err(e);
         }
 
-        let relay_result = if config.general.use_middle_proxy {
+        let route_snapshot = route_runtime.snapshot();
+        let session_id = rng.u64();
+        let relay_result = if config.general.use_middle_proxy
+            && matches!(route_snapshot.mode, RelayRouteMode::Middle)
+        {
             if let Some(ref pool) = me_pool {
                 handle_via_middle_proxy(
                     client_reader,
@@ -725,6 +747,9 @@ impl RunningClientHandler {
                     buffer_pool,
                     local_addr,
                     rng,
+                    route_runtime.subscribe(),
+                    route_snapshot,
+                    session_id,
                 )
                 .await
             } else {
@@ -738,6 +763,9 @@ impl RunningClientHandler {
                     config,
                     buffer_pool,
                     rng,
+                    route_runtime.subscribe(),
+                    route_snapshot,
+                    session_id,
                 )
                 .await
             }
@@ -752,6 +780,9 @@ impl RunningClientHandler {
                 config,
                 buffer_pool,
                 rng,
+                route_runtime.subscribe(),
+                route_snapshot,
+                session_id,
             )
             .await
         };
@@ -775,12 +806,8 @@ impl RunningClientHandler {
             });
         }
 
-        let mut ip_reserved = false;
-        // IP limit check
-        match ip_tracker.check_and_add(user, peer_addr.ip()).await {
-            Ok(()) => {
-                ip_reserved = true;
-            }
+        let ip_reserved = match ip_tracker.check_and_add(user, peer_addr.ip()).await {
+            Ok(()) => true,
             Err(reason) => {
                 warn!(
                     user = %user,
@@ -792,7 +819,8 @@ impl RunningClientHandler {
                     user: user.to_string(),
                 });
             }
-        }
+        };
+        // IP limit check
 
         if let Some(limit) = config.access.user_max_tcp_conns.get(user)
             && stats.get_user_curr_connects(user) >= *limit as u64

src/proxy/direct_relay.rs

@@ -5,14 +5,19 @@ use std::sync::Arc;
 
 use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt};
 use tokio::net::TcpStream;
+use tokio::sync::watch;
 use tracing::{debug, info, warn};
 
 use crate::config::ProxyConfig;
 use crate::crypto::SecureRandom;
-use crate::error::Result;
+use crate::error::{ProxyError, Result};
 use crate::protocol::constants::*;
 use crate::proxy::handshake::{HandshakeSuccess, encrypt_tg_nonce_with_ciphers, generate_tg_nonce};
 use crate::proxy::relay::relay_bidirectional;
+use crate::proxy::route_mode::{
+    RelayRouteMode, RouteCutoverState, ROUTE_SWITCH_ERROR_MSG, affected_cutover_state,
+    cutover_stagger_delay,
+};
 use crate::stats::Stats;
 use crate::stream::{BufferPool, CryptoReader, CryptoWriter};
 use crate::transport::UpstreamManager;
@@ -26,6 +31,9 @@ pub(crate) async fn handle_via_direct<R, W>(
     config: Arc<ProxyConfig>,
     buffer_pool: Arc<BufferPool>,
     rng: Arc<SecureRandom>,
+    mut route_rx: watch::Receiver<RouteCutoverState>,
+    route_snapshot: RouteCutoverState,
+    session_id: u64,
 ) -> Result<()>
 where
     R: AsyncRead + Unpin + Send + 'static,
@@ -64,11 +72,41 @@ where
         client_writer,
         tg_reader,
         tg_writer,
+        config.general.direct_relay_copy_buf_c2s_bytes,
+        config.general.direct_relay_copy_buf_s2c_bytes,
         user,
         Arc::clone(&stats),
         buffer_pool,
-    )
-    .await;
+    );
+    tokio::pin!(relay_result);
+    let relay_result = loop {
+        if let Some(cutover) = affected_cutover_state(
+            &route_rx,
+            RelayRouteMode::Direct,
+            route_snapshot.generation,
+        ) {
+            let delay = cutover_stagger_delay(session_id, cutover.generation);
+            warn!(
+                user = %user,
+                target_mode = cutover.mode.as_str(),
+                cutover_generation = cutover.generation,
+                delay_ms = delay.as_millis() as u64,
+                "Cutover affected direct session, closing client connection"
+            );
+            tokio::time::sleep(delay).await;
+            break Err(ProxyError::Proxy(ROUTE_SWITCH_ERROR_MSG.to_string()));
+        }
+        tokio::select! {
+            result = &mut relay_result => {
+                break result;
+            }
+            changed = route_rx.changed() => {
+                if changed.is_err() {
+                    break relay_result.await;
+                }
+            }
+        }
+    };
 
     stats.decrement_current_connections_direct();
     stats.decrement_user_curr_connects(user);

src/proxy/middle_relay.rs

@@ -8,7 +8,7 @@ use std::time::{Duration, Instant};
 
 use bytes::Bytes;
 use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
-use tokio::sync::{mpsc, oneshot};
+use tokio::sync::{mpsc, oneshot, watch};
 use tracing::{debug, trace, warn};
 
 use crate::config::ProxyConfig;
@@ -16,6 +16,10 @@ use crate::crypto::SecureRandom;
 use crate::error::{ProxyError, Result};
 use crate::protocol::constants::{*, secure_padding_len};
 use crate::proxy::handshake::HandshakeSuccess;
+use crate::proxy::route_mode::{
+    RelayRouteMode, RouteCutoverState, ROUTE_SWITCH_ERROR_MSG, affected_cutover_state,
+    cutover_stagger_delay,
+};
 use crate::stats::Stats;
 use crate::stream::{BufferPool, CryptoReader, CryptoWriter};
 use crate::transport::middle_proxy::{MePool, MeResponse, proto_flags_for_tag};
@@ -27,9 +31,11 @@ enum C2MeCommand {
 
 const DESYNC_DEDUP_WINDOW: Duration = Duration::from_secs(60);
 const DESYNC_ERROR_CLASS: &str = "frame_too_large_crypto_desync";
-const C2ME_CHANNEL_CAPACITY: usize = 1024;
+const C2ME_CHANNEL_CAPACITY_FALLBACK: usize = 128;
 const C2ME_SOFT_PRESSURE_MIN_FREE_SLOTS: usize = 64;
 const C2ME_SENDER_FAIRNESS_BUDGET: usize = 32;
+const ME_D2C_FLUSH_BATCH_MAX_FRAMES_MIN: usize = 1;
+const ME_D2C_FLUSH_BATCH_MAX_BYTES_MIN: usize = 4096;
 static DESYNC_DEDUP: OnceLock<Mutex<HashMap<u64, Instant>>> = OnceLock::new();
 
 struct RelayForensicsState {
@@ -44,6 +50,31 @@ struct RelayForensicsState {
     desync_all_full: bool,
 }
 
+#[derive(Clone, Copy)]
+struct MeD2cFlushPolicy {
+    max_frames: usize,
+    max_bytes: usize,
+    max_delay: Duration,
+    ack_flush_immediate: bool,
+}
+
+impl MeD2cFlushPolicy {
+    fn from_config(config: &ProxyConfig) -> Self {
+        Self {
+            max_frames: config
+                .general
+                .me_d2c_flush_batch_max_frames
+                .max(ME_D2C_FLUSH_BATCH_MAX_FRAMES_MIN),
+            max_bytes: config
+                .general
+                .me_d2c_flush_batch_max_bytes
+                .max(ME_D2C_FLUSH_BATCH_MAX_BYTES_MIN),
+            max_delay: Duration::from_micros(config.general.me_d2c_flush_batch_max_delay_us),
+            ack_flush_immediate: config.general.me_d2c_ack_flush_immediate,
+        }
+    }
+}
+
 fn hash_value<T: Hash>(value: &T) -> u64 {
     let mut hasher = DefaultHasher::new();
     value.hash(&mut hasher);
@@ -201,6 +232,9 @@ pub(crate) async fn handle_via_middle_proxy<R, W>(
     _buffer_pool: Arc<BufferPool>,
     local_addr: SocketAddr,
     rng: Arc<SecureRandom>,
+    mut route_rx: watch::Receiver<RouteCutoverState>,
+    route_snapshot: RouteCutoverState,
+    session_id: u64,
 ) -> Result<()>
 where
     R: AsyncRead + Unpin + Send + 'static,
@@ -240,6 +274,27 @@ where
     stats.increment_user_curr_connects(&user);
     stats.increment_current_connections_me();
 
+    if let Some(cutover) = affected_cutover_state(
+        &route_rx,
+        RelayRouteMode::Middle,
+        route_snapshot.generation,
+    ) {
+        let delay = cutover_stagger_delay(session_id, cutover.generation);
+        warn!(
+            conn_id,
+            target_mode = cutover.mode.as_str(),
+            cutover_generation = cutover.generation,
+            delay_ms = delay.as_millis() as u64,
+            "Cutover affected middle session before relay start, closing client connection"
+        );
+        tokio::time::sleep(delay).await;
+        let _ = me_pool.send_close(conn_id).await;
+        me_pool.registry().unregister(conn_id).await;
+        stats.decrement_current_connections_me();
+        stats.decrement_user_curr_connects(&user);
+        return Err(ProxyError::Proxy(ROUTE_SWITCH_ERROR_MSG.to_string()));
+    }
+
     // Per-user ad_tag from access.user_ad_tags; fallback to general.ad_tag (hot-reloadable)
     let user_tag: Option<Vec<u8>> = config
         .access
@@ -271,7 +326,11 @@ where
 
     let frame_limit = config.general.max_client_frame;
 
-    let (c2me_tx, mut c2me_rx) = mpsc::channel::<C2MeCommand>(C2ME_CHANNEL_CAPACITY);
+    let c2me_channel_capacity = config
+        .general
+        .me_c2me_channel_capacity
+        .max(C2ME_CHANNEL_CAPACITY_FALLBACK);
+    let (c2me_tx, mut c2me_rx) = mpsc::channel::<C2MeCommand>(c2me_channel_capacity);
     let me_pool_c2me = me_pool.clone();
     let effective_tag = effective_tag;
     let c2me_sender = tokio::spawn(async move {
@@ -309,71 +368,152 @@ where
     let rng_clone = rng.clone();
     let user_clone = user.clone();
     let bytes_me2c_clone = bytes_me2c.clone();
+    let d2c_flush_policy = MeD2cFlushPolicy::from_config(&config);
     let me_writer = tokio::spawn(async move {
         let mut writer = crypto_writer;
         let mut frame_buf = Vec::with_capacity(16 * 1024);
         loop {
             tokio::select! {
                 msg = me_rx_task.recv() => {
-                    match msg {
-                        Some(MeResponse::Data { flags, data }) => {
-                            trace!(conn_id, bytes = data.len(), flags, "ME->C data");
-                            bytes_me2c_clone.fetch_add(data.len() as u64, Ordering::Relaxed);
-                            stats_clone.add_user_octets_to(&user_clone, data.len() as u64);
-                            write_client_payload(
-                                &mut writer,
-                                proto_tag,
-                                flags,
-                                &data,
-                                rng_clone.as_ref(),
-                                &mut frame_buf,
-                            )
-                            .await?;
+                    let Some(first) = msg else {
+                        debug!(conn_id, "ME channel closed");
+                        return Err(ProxyError::Proxy("ME connection lost".into()));
+                    };
 
-                            // Drain all immediately queued ME responses and flush once.
-                            while let Ok(next) = me_rx_task.try_recv() {
-                                match next {
-                                    MeResponse::Data { flags, data } => {
-                                        trace!(conn_id, bytes = data.len(), flags, "ME->C data (batched)");
-                                        bytes_me2c_clone.fetch_add(data.len() as u64, Ordering::Relaxed);
-                                        stats_clone.add_user_octets_to(&user_clone, data.len() as u64);
-                                        write_client_payload(
-                                            &mut writer,
-                                            proto_tag,
-                                            flags,
-                                            &data,
-                                            rng_clone.as_ref(),
-                                            &mut frame_buf,
-                                        ).await?;
+                    let mut batch_frames = 0usize;
+                    let mut batch_bytes = 0usize;
+                    let mut flush_immediately;
+
+                    match process_me_writer_response(
+                        first,
+                        &mut writer,
+                        proto_tag,
+                        rng_clone.as_ref(),
+                        &mut frame_buf,
+                        stats_clone.as_ref(),
+                        &user_clone,
+                        bytes_me2c_clone.as_ref(),
+                        conn_id,
+                        d2c_flush_policy.ack_flush_immediate,
+                        false,
+                    ).await? {
+                        MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                            batch_frames = batch_frames.saturating_add(frames);
+                            batch_bytes = batch_bytes.saturating_add(bytes);
+                            flush_immediately = immediate;
+                        }
+                        MeWriterResponseOutcome::Close => {
+                            let _ = writer.flush().await;
+                            return Ok(());
+                        }
+                    }
+
+                    while !flush_immediately
+                        && batch_frames < d2c_flush_policy.max_frames
+                        && batch_bytes < d2c_flush_policy.max_bytes
+                    {
+                        let Ok(next) = me_rx_task.try_recv() else {
+                            break;
+                        };
+
+                        match process_me_writer_response(
+                            next,
+                            &mut writer,
+                            proto_tag,
+                            rng_clone.as_ref(),
+                            &mut frame_buf,
+                            stats_clone.as_ref(),
+                            &user_clone,
+                            bytes_me2c_clone.as_ref(),
+                            conn_id,
+                            d2c_flush_policy.ack_flush_immediate,
+                            true,
+                        ).await? {
+                            MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                                batch_frames = batch_frames.saturating_add(frames);
+                                batch_bytes = batch_bytes.saturating_add(bytes);
+                                flush_immediately |= immediate;
+                            }
+                            MeWriterResponseOutcome::Close => {
+                                let _ = writer.flush().await;
+                                return Ok(());
+                            }
+                        }
+                    }
+
+                    if !flush_immediately
+                        && !d2c_flush_policy.max_delay.is_zero()
+                        && batch_frames < d2c_flush_policy.max_frames
+                        && batch_bytes < d2c_flush_policy.max_bytes
+                    {
+                        match tokio::time::timeout(d2c_flush_policy.max_delay, me_rx_task.recv()).await {
+                            Ok(Some(next)) => {
+                                match process_me_writer_response(
+                                    next,
+                                    &mut writer,
+                                    proto_tag,
+                                    rng_clone.as_ref(),
+                                    &mut frame_buf,
+                                    stats_clone.as_ref(),
+                                    &user_clone,
+                                    bytes_me2c_clone.as_ref(),
+                                    conn_id,
+                                    d2c_flush_policy.ack_flush_immediate,
+                                    true,
+                                ).await? {
+                                    MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                                        batch_frames = batch_frames.saturating_add(frames);
+                                        batch_bytes = batch_bytes.saturating_add(bytes);
+                                        flush_immediately |= immediate;
                                     }
-                                    MeResponse::Ack(confirm) => {
-                                        trace!(conn_id, confirm, "ME->C quickack (batched)");
-                                        write_client_ack(&mut writer, proto_tag, confirm).await?;
-                                    }
-                                    MeResponse::Close => {
-                                        debug!(conn_id, "ME sent close (batched)");
+                                    MeWriterResponseOutcome::Close => {
                                         let _ = writer.flush().await;
                                         return Ok(());
                                     }
                                 }
-                            }
 
-                            writer.flush().await.map_err(ProxyError::Io)?;
-                        }
-                        Some(MeResponse::Ack(confirm)) => {
-                            trace!(conn_id, confirm, "ME->C quickack");
-                            write_client_ack(&mut writer, proto_tag, confirm).await?;
-                        }
-                        Some(MeResponse::Close) => {
-                            debug!(conn_id, "ME sent close");
-                            let _ = writer.flush().await;
-                            return Ok(());
-                        }
-                        None => {
-                            debug!(conn_id, "ME channel closed");
-                            return Err(ProxyError::Proxy("ME connection lost".into()));
+                                while !flush_immediately
+                                    && batch_frames < d2c_flush_policy.max_frames
+                                    && batch_bytes < d2c_flush_policy.max_bytes
+                                {
+                                    let Ok(extra) = me_rx_task.try_recv() else {
+                                        break;
+                                    };
+
+                                    match process_me_writer_response(
+                                        extra,
+                                        &mut writer,
+                                        proto_tag,
+                                        rng_clone.as_ref(),
+                                        &mut frame_buf,
+                                        stats_clone.as_ref(),
+                                        &user_clone,
+                                        bytes_me2c_clone.as_ref(),
+                                        conn_id,
+                                        d2c_flush_policy.ack_flush_immediate,
+                                        true,
+                                    ).await? {
+                                        MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                                            batch_frames = batch_frames.saturating_add(frames);
+                                            batch_bytes = batch_bytes.saturating_add(bytes);
+                                            flush_immediately |= immediate;
+                                        }
+                                        MeWriterResponseOutcome::Close => {
+                                            let _ = writer.flush().await;
+                                            return Ok(());
+                                        }
+                                    }
+                                }
+                            }
+                            Ok(None) => {
+                                debug!(conn_id, "ME channel closed");
+                                return Err(ProxyError::Proxy("ME connection lost".into()));
+                            }
+                            Err(_) => {}
                         }
                     }
+
+                    writer.flush().await.map_err(ProxyError::Io)?;
                 }
                 _ = &mut stop_rx => {
                     debug!(conn_id, "ME writer stop signal");
@@ -386,46 +526,75 @@ where
     let mut main_result: Result<()> = Ok(());
     let mut client_closed = false;
     let mut frame_counter: u64 = 0;
+    let mut route_watch_open = true;
     loop {
-        match read_client_payload(
-            &mut crypto_reader,
-            proto_tag,
-            frame_limit,
-            &forensics,
-            &mut frame_counter,
-            &stats,
-        ).await {
-            Ok(Some((payload, quickack))) => {
-                trace!(conn_id, bytes = payload.len(), "C->ME frame");
-                forensics.bytes_c2me = forensics
-                    .bytes_c2me
-                    .saturating_add(payload.len() as u64);
-                stats.add_user_octets_from(&user, payload.len() as u64);
-                let mut flags = proto_flags;
-                if quickack {
-                    flags |= RPC_FLAG_QUICKACK;
-                }
-                if payload.len() >= 8 && payload[..8].iter().all(|b| *b == 0) {
-                    flags |= RPC_FLAG_NOT_ENCRYPTED;
-                }
-                // Keep client read loop lightweight: route heavy ME send path via a dedicated task.
-                if enqueue_c2me_command(&c2me_tx, C2MeCommand::Data { payload, flags })
-                    .await
-                    .is_err()
-                {
-                    main_result = Err(ProxyError::Proxy("ME sender channel closed".into()));
-                    break;
+        if let Some(cutover) = affected_cutover_state(
+            &route_rx,
+            RelayRouteMode::Middle,
+            route_snapshot.generation,
+        ) {
+            let delay = cutover_stagger_delay(session_id, cutover.generation);
+            warn!(
+                conn_id,
+                target_mode = cutover.mode.as_str(),
+                cutover_generation = cutover.generation,
+                delay_ms = delay.as_millis() as u64,
+                "Cutover affected middle session, closing client connection"
+            );
+            tokio::time::sleep(delay).await;
+            let _ = enqueue_c2me_command(&c2me_tx, C2MeCommand::Close).await;
+            main_result = Err(ProxyError::Proxy(ROUTE_SWITCH_ERROR_MSG.to_string()));
+            break;
+        }
+
+        tokio::select! {
+            changed = route_rx.changed(), if route_watch_open => {
+                if changed.is_err() {
+                    route_watch_open = false;
                 }
             }
-            Ok(None) => {
-                debug!(conn_id, "Client EOF");
-                client_closed = true;
-                let _ = enqueue_c2me_command(&c2me_tx, C2MeCommand::Close).await;
-                break;
-            }
-            Err(e) => {
-                main_result = Err(e);
-                break;
+            payload_result = read_client_payload(
+                &mut crypto_reader,
+                proto_tag,
+                frame_limit,
+                &forensics,
+                &mut frame_counter,
+                &stats,
+            ) => {
+                match payload_result {
+                    Ok(Some((payload, quickack))) => {
+                        trace!(conn_id, bytes = payload.len(), "C->ME frame");
+                        forensics.bytes_c2me = forensics
+                            .bytes_c2me
+                            .saturating_add(payload.len() as u64);
+                        stats.add_user_octets_from(&user, payload.len() as u64);
+                        let mut flags = proto_flags;
+                        if quickack {
+                            flags |= RPC_FLAG_QUICKACK;
+                        }
+                        if payload.len() >= 8 && payload[..8].iter().all(|b| *b == 0) {
+                            flags |= RPC_FLAG_NOT_ENCRYPTED;
+                        }
+                        // Keep client read loop lightweight: route heavy ME send path via a dedicated task.
+                        if enqueue_c2me_command(&c2me_tx, C2MeCommand::Data { payload, flags })
+                            .await
+                            .is_err()
+                        {
+                            main_result = Err(ProxyError::Proxy("ME sender channel closed".into()));
+                            break;
+                        }
+                    }
+                    Ok(None) => {
+                        debug!(conn_id, "Client EOF");
+                        client_closed = true;
+                        let _ = enqueue_c2me_command(&c2me_tx, C2MeCommand::Close).await;
+                        break;
+                    }
+                    Err(e) => {
+                        main_result = Err(e);
+                        break;
+                    }
+                }
             }
         }
     }
@@ -583,6 +752,81 @@ where
     }
 }
 
+enum MeWriterResponseOutcome {
+    Continue {
+        frames: usize,
+        bytes: usize,
+        flush_immediately: bool,
+    },
+    Close,
+}
+
+async fn process_me_writer_response<W>(
+    response: MeResponse,
+    client_writer: &mut CryptoWriter<W>,
+    proto_tag: ProtoTag,
+    rng: &SecureRandom,
+    frame_buf: &mut Vec<u8>,
+    stats: &Stats,
+    user: &str,
+    bytes_me2c: &AtomicU64,
+    conn_id: u64,
+    ack_flush_immediate: bool,
+    batched: bool,
+) -> Result<MeWriterResponseOutcome>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    match response {
+        MeResponse::Data { flags, data } => {
+            if batched {
+                trace!(conn_id, bytes = data.len(), flags, "ME->C data (batched)");
+            } else {
+                trace!(conn_id, bytes = data.len(), flags, "ME->C data");
+            }
+            bytes_me2c.fetch_add(data.len() as u64, Ordering::Relaxed);
+            stats.add_user_octets_to(user, data.len() as u64);
+            write_client_payload(
+                client_writer,
+                proto_tag,
+                flags,
+                &data,
+                rng,
+                frame_buf,
+            )
+            .await?;
+
+            Ok(MeWriterResponseOutcome::Continue {
+                frames: 1,
+                bytes: data.len(),
+                flush_immediately: false,
+            })
+        }
+        MeResponse::Ack(confirm) => {
+            if batched {
+                trace!(conn_id, confirm, "ME->C quickack (batched)");
+            } else {
+                trace!(conn_id, confirm, "ME->C quickack");
+            }
+            write_client_ack(client_writer, proto_tag, confirm).await?;
+
+            Ok(MeWriterResponseOutcome::Continue {
+                frames: 1,
+                bytes: 4,
+                flush_immediately: ack_flush_immediate,
+            })
+        }
+        MeResponse::Close => {
+            if batched {
+                debug!(conn_id, "ME sent close (batched)");
+            } else {
+                debug!(conn_id, "ME sent close");
+            }
+            Ok(MeWriterResponseOutcome::Close)
+        }
+    }
+}
+
 async fn write_client_payload<W>(
     client_writer: &mut CryptoWriter<W>,
     proto_tag: ProtoTag,
@@ -692,9 +936,7 @@ where
     client_writer
         .write_all(&bytes)
         .await
-        .map_err(ProxyError::Io)?;
-    // ACK should remain low-latency.
-    client_writer.flush().await.map_err(ProxyError::Io)
+        .map_err(ProxyError::Io)
 }
 
 #[cfg(test)]

src/proxy/mod.rs

@@ -5,6 +5,7 @@ pub mod direct_relay;
 pub mod handshake;
 pub mod masking;
 pub mod middle_relay;
+pub mod route_mode;
 pub mod relay;
 
 pub use client::ClientHandler;

src/proxy/relay.rs

@@ -57,7 +57,9 @@ use std::sync::Arc;
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::task::{Context, Poll};
 use std::time::Duration;
-use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt, ReadBuf, copy_bidirectional};
+use tokio::io::{
+    AsyncRead, AsyncWrite, AsyncWriteExt, ReadBuf, copy_bidirectional_with_sizes,
+};
 use tokio::time::Instant;
 use tracing::{debug, trace, warn};
 use crate::error::Result;
@@ -296,9 +298,8 @@ impl<S: AsyncWrite + Unpin> AsyncWrite for StatsIo<S> {
 ///
 /// ## API compatibility
 ///
-/// Signature is identical to the previous implementation. The `_buffer_pool`
-/// parameter is retained for call-site compatibility — `copy_bidirectional`
-/// manages its own internal buffers (8 KB per direction).
+/// The `_buffer_pool` parameter is retained for call-site compatibility.
+/// Effective relay copy buffers are configured by `c2s_buf_size` / `s2c_buf_size`.
 ///
 /// ## Guarantees preserved
 ///
@@ -312,6 +313,8 @@ pub async fn relay_bidirectional<CR, CW, SR, SW>(
     client_writer: CW,
     server_reader: SR,
     server_writer: SW,
+    c2s_buf_size: usize,
+    s2c_buf_size: usize,
     user: &str,
     stats: Arc<Stats>,
     _buffer_pool: Arc<BufferPool>,
@@ -402,7 +405,12 @@ where
     // When the watchdog fires, select! drops the copy future,
     // releasing the &mut borrows on client and server.
     let copy_result = tokio::select! {
-        result = copy_bidirectional(&mut client, &mut server) => Some(result),
+        result = copy_bidirectional_with_sizes(
+            &mut client,
+            &mut server,
+            c2s_buf_size.max(1),
+            s2c_buf_size.max(1),
+        ) => Some(result),
         _ = watchdog => None, // Activity timeout — cancel relay
     };
 
@@ -463,4 +471,4 @@ where
             Ok(())
         }
     }
-}
+}

src/proxy/route_mode.rs

@@ -0,0 +1,142 @@
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU8, AtomicU64, Ordering};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use tokio::sync::watch;
+
+pub(crate) const ROUTE_SWITCH_ERROR_MSG: &str = "Route mode switched by cutover";
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+#[repr(u8)]
+pub(crate) enum RelayRouteMode {
+    Direct = 0,
+    Middle = 1,
+}
+
+impl RelayRouteMode {
+    pub(crate) fn as_u8(self) -> u8 {
+        self as u8
+    }
+
+    pub(crate) fn from_u8(value: u8) -> Self {
+        match value {
+            1 => Self::Middle,
+            _ => Self::Direct,
+        }
+    }
+
+    pub(crate) fn as_str(self) -> &'static str {
+        match self {
+            Self::Direct => "direct",
+            Self::Middle => "middle",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct RouteCutoverState {
+    pub mode: RelayRouteMode,
+    pub generation: u64,
+}
+
+#[derive(Clone)]
+pub(crate) struct RouteRuntimeController {
+    mode: Arc<AtomicU8>,
+    generation: Arc<AtomicU64>,
+    direct_since_epoch_secs: Arc<AtomicU64>,
+    tx: watch::Sender<RouteCutoverState>,
+}
+
+impl RouteRuntimeController {
+    pub(crate) fn new(initial_mode: RelayRouteMode) -> Self {
+        let initial = RouteCutoverState {
+            mode: initial_mode,
+            generation: 0,
+        };
+        let (tx, _rx) = watch::channel(initial);
+        let direct_since_epoch_secs = if matches!(initial_mode, RelayRouteMode::Direct) {
+            now_epoch_secs()
+        } else {
+            0
+        };
+        Self {
+            mode: Arc::new(AtomicU8::new(initial_mode.as_u8())),
+            generation: Arc::new(AtomicU64::new(0)),
+            direct_since_epoch_secs: Arc::new(AtomicU64::new(direct_since_epoch_secs)),
+            tx,
+        }
+    }
+
+    pub(crate) fn snapshot(&self) -> RouteCutoverState {
+        RouteCutoverState {
+            mode: RelayRouteMode::from_u8(self.mode.load(Ordering::Relaxed)),
+            generation: self.generation.load(Ordering::Relaxed),
+        }
+    }
+
+    pub(crate) fn subscribe(&self) -> watch::Receiver<RouteCutoverState> {
+        self.tx.subscribe()
+    }
+
+    pub(crate) fn direct_since_epoch_secs(&self) -> Option<u64> {
+        let value = self.direct_since_epoch_secs.load(Ordering::Relaxed);
+        (value > 0).then_some(value)
+    }
+
+    pub(crate) fn set_mode(&self, mode: RelayRouteMode) -> Option<RouteCutoverState> {
+        let previous = self.mode.swap(mode.as_u8(), Ordering::Relaxed);
+        if previous == mode.as_u8() {
+            return None;
+        }
+        if matches!(mode, RelayRouteMode::Direct) {
+            self.direct_since_epoch_secs
+                .store(now_epoch_secs(), Ordering::Relaxed);
+        } else {
+            self.direct_since_epoch_secs.store(0, Ordering::Relaxed);
+        }
+        let generation = self.generation.fetch_add(1, Ordering::Relaxed) + 1;
+        let next = RouteCutoverState { mode, generation };
+        self.tx.send_replace(next);
+        Some(next)
+    }
+}
+
+fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|value| value.as_secs())
+        .unwrap_or(0)
+}
+
+pub(crate) fn is_session_affected_by_cutover(
+    current: RouteCutoverState,
+    _session_mode: RelayRouteMode,
+    session_generation: u64,
+) -> bool {
+    current.generation > session_generation
+}
+
+pub(crate) fn affected_cutover_state(
+    rx: &watch::Receiver<RouteCutoverState>,
+    session_mode: RelayRouteMode,
+    session_generation: u64,
+) -> Option<RouteCutoverState> {
+    let current = *rx.borrow();
+    if is_session_affected_by_cutover(current, session_mode, session_generation) {
+        return Some(current);
+    }
+    None
+}
+
+pub(crate) fn cutover_stagger_delay(session_id: u64, generation: u64) -> Duration {
+    let mut value = session_id
+        ^ generation.rotate_left(17)
+        ^ 0x9e37_79b9_7f4a_7c15;
+    value ^= value >> 30;
+    value = value.wrapping_mul(0xbf58_476d_1ce4_e5b9);
+    value ^= value >> 27;
+    value = value.wrapping_mul(0x94d0_49bb_1331_11eb);
+    value ^= value >> 31;
+    let ms = 1000 + (value % 1000);
+    Duration::from_millis(ms)
+}

src/stats/mod.rs

@@ -16,7 +16,7 @@ use std::collections::hash_map::DefaultHasher;
 use std::collections::VecDeque;
 use tracing::debug;
 
-use crate::config::MeTelemetryLevel;
+use crate::config::{MeTelemetryLevel, MeWriterPickMode};
 use self::telemetry::TelemetryPolicy;
 
 // ============= Stats =============
@@ -95,6 +95,18 @@ pub struct Stats {
     me_route_drop_queue_full: AtomicU64,
     me_route_drop_queue_full_base: AtomicU64,
     me_route_drop_queue_full_high: AtomicU64,
+    me_writer_pick_sorted_rr_success_try_total: AtomicU64,
+    me_writer_pick_sorted_rr_success_fallback_total: AtomicU64,
+    me_writer_pick_sorted_rr_full_total: AtomicU64,
+    me_writer_pick_sorted_rr_closed_total: AtomicU64,
+    me_writer_pick_sorted_rr_no_candidate_total: AtomicU64,
+    me_writer_pick_p2c_success_try_total: AtomicU64,
+    me_writer_pick_p2c_success_fallback_total: AtomicU64,
+    me_writer_pick_p2c_full_total: AtomicU64,
+    me_writer_pick_p2c_closed_total: AtomicU64,
+    me_writer_pick_p2c_no_candidate_total: AtomicU64,
+    me_writer_pick_blocking_fallback_total: AtomicU64,
+    me_writer_pick_mode_switch_total: AtomicU64,
     me_socks_kdf_strict_reject: AtomicU64,
     me_socks_kdf_compat_fallback: AtomicU64,
     secure_padding_invalid: AtomicU64,
@@ -497,6 +509,93 @@ impl Stats {
             self.me_route_drop_queue_full_high.fetch_add(1, Ordering::Relaxed);
         }
     }
+    pub fn increment_me_writer_pick_success_try_total(&self, mode: MeWriterPickMode) {
+        if !self.telemetry_me_allows_normal() {
+            return;
+        }
+        match mode {
+            MeWriterPickMode::SortedRr => {
+                self.me_writer_pick_sorted_rr_success_try_total
+                    .fetch_add(1, Ordering::Relaxed);
+            }
+            MeWriterPickMode::P2c => {
+                self.me_writer_pick_p2c_success_try_total
+                    .fetch_add(1, Ordering::Relaxed);
+            }
+        }
+    }
+    pub fn increment_me_writer_pick_success_fallback_total(&self, mode: MeWriterPickMode) {
+        if !self.telemetry_me_allows_normal() {
+            return;
+        }
+        match mode {
+            MeWriterPickMode::SortedRr => {
+                self.me_writer_pick_sorted_rr_success_fallback_total
+                    .fetch_add(1, Ordering::Relaxed);
+            }
+            MeWriterPickMode::P2c => {
+                self.me_writer_pick_p2c_success_fallback_total
+                    .fetch_add(1, Ordering::Relaxed);
+            }
+        }
+    }
+    pub fn increment_me_writer_pick_full_total(&self, mode: MeWriterPickMode) {
+        if !self.telemetry_me_allows_normal() {
+            return;
+        }
+        match mode {
+            MeWriterPickMode::SortedRr => {
+                self.me_writer_pick_sorted_rr_full_total
+                    .fetch_add(1, Ordering::Relaxed);
+            }
+            MeWriterPickMode::P2c => {
+                self.me_writer_pick_p2c_full_total
+                    .fetch_add(1, Ordering::Relaxed);
+            }
+        }
+    }
+    pub fn increment_me_writer_pick_closed_total(&self, mode: MeWriterPickMode) {
+        if !self.telemetry_me_allows_normal() {
+            return;
+        }
+        match mode {
+            MeWriterPickMode::SortedRr => {
+                self.me_writer_pick_sorted_rr_closed_total
+                    .fetch_add(1, Ordering::Relaxed);
+            }
+            MeWriterPickMode::P2c => {
+                self.me_writer_pick_p2c_closed_total
+                    .fetch_add(1, Ordering::Relaxed);
+            }
+        }
+    }
+    pub fn increment_me_writer_pick_no_candidate_total(&self, mode: MeWriterPickMode) {
+        if !self.telemetry_me_allows_normal() {
+            return;
+        }
+        match mode {
+            MeWriterPickMode::SortedRr => {
+                self.me_writer_pick_sorted_rr_no_candidate_total
+                    .fetch_add(1, Ordering::Relaxed);
+            }
+            MeWriterPickMode::P2c => {
+                self.me_writer_pick_p2c_no_candidate_total
+                    .fetch_add(1, Ordering::Relaxed);
+            }
+        }
+    }
+    pub fn increment_me_writer_pick_blocking_fallback_total(&self) {
+        if self.telemetry_me_allows_normal() {
+            self.me_writer_pick_blocking_fallback_total
+                .fetch_add(1, Ordering::Relaxed);
+        }
+    }
+    pub fn increment_me_writer_pick_mode_switch_total(&self) {
+        if self.telemetry_me_allows_normal() {
+            self.me_writer_pick_mode_switch_total
+                .fetch_add(1, Ordering::Relaxed);
+        }
+    }
     pub fn increment_me_socks_kdf_strict_reject(&self) {
         if self.telemetry_me_allows_normal() {
             self.me_socks_kdf_strict_reject.fetch_add(1, Ordering::Relaxed);
@@ -1001,6 +1100,52 @@ impl Stats {
     pub fn get_me_route_drop_queue_full_high(&self) -> u64 {
         self.me_route_drop_queue_full_high.load(Ordering::Relaxed)
     }
+    pub fn get_me_writer_pick_sorted_rr_success_try_total(&self) -> u64 {
+        self.me_writer_pick_sorted_rr_success_try_total
+            .load(Ordering::Relaxed)
+    }
+    pub fn get_me_writer_pick_sorted_rr_success_fallback_total(&self) -> u64 {
+        self.me_writer_pick_sorted_rr_success_fallback_total
+            .load(Ordering::Relaxed)
+    }
+    pub fn get_me_writer_pick_sorted_rr_full_total(&self) -> u64 {
+        self.me_writer_pick_sorted_rr_full_total
+            .load(Ordering::Relaxed)
+    }
+    pub fn get_me_writer_pick_sorted_rr_closed_total(&self) -> u64 {
+        self.me_writer_pick_sorted_rr_closed_total
+            .load(Ordering::Relaxed)
+    }
+    pub fn get_me_writer_pick_sorted_rr_no_candidate_total(&self) -> u64 {
+        self.me_writer_pick_sorted_rr_no_candidate_total
+            .load(Ordering::Relaxed)
+    }
+    pub fn get_me_writer_pick_p2c_success_try_total(&self) -> u64 {
+        self.me_writer_pick_p2c_success_try_total
+            .load(Ordering::Relaxed)
+    }
+    pub fn get_me_writer_pick_p2c_success_fallback_total(&self) -> u64 {
+        self.me_writer_pick_p2c_success_fallback_total
+            .load(Ordering::Relaxed)
+    }
+    pub fn get_me_writer_pick_p2c_full_total(&self) -> u64 {
+        self.me_writer_pick_p2c_full_total.load(Ordering::Relaxed)
+    }
+    pub fn get_me_writer_pick_p2c_closed_total(&self) -> u64 {
+        self.me_writer_pick_p2c_closed_total.load(Ordering::Relaxed)
+    }
+    pub fn get_me_writer_pick_p2c_no_candidate_total(&self) -> u64 {
+        self.me_writer_pick_p2c_no_candidate_total
+            .load(Ordering::Relaxed)
+    }
+    pub fn get_me_writer_pick_blocking_fallback_total(&self) -> u64 {
+        self.me_writer_pick_blocking_fallback_total
+            .load(Ordering::Relaxed)
+    }
+    pub fn get_me_writer_pick_mode_switch_total(&self) -> u64 {
+        self.me_writer_pick_mode_switch_total
+            .load(Ordering::Relaxed)
+    }
     pub fn get_me_socks_kdf_strict_reject(&self) -> u64 {
         self.me_socks_kdf_strict_reject.load(Ordering::Relaxed)
     }

src/tls_front/cache.rs

@@ -8,7 +8,9 @@ use tokio::sync::RwLock;
 use tokio::time::sleep;
 use tracing::{debug, warn, info};
 
-use crate::tls_front::types::{CachedTlsData, ParsedServerHello, TlsFetchResult};
+use crate::tls_front::types::{
+    CachedTlsData, ParsedServerHello, TlsBehaviorProfile, TlsFetchResult,
+};
 
 /// Lightweight in-memory + optional on-disk cache for TLS fronting data.
 #[derive(Debug)]
@@ -37,6 +39,7 @@ impl TlsFrontCache {
             cert_payload: None,
             app_data_records_sizes: vec![default_len],
             total_app_data_len: default_len,
+            behavior_profile: TlsBehaviorProfile::default(),
             fetched_at: SystemTime::now(),
             domain: "default".to_string(),
         });
@@ -189,6 +192,7 @@ impl TlsFrontCache {
             cert_payload: fetched.cert_payload,
             app_data_records_sizes: fetched.app_data_records_sizes.clone(),
             total_app_data_len: fetched.total_app_data_len,
+            behavior_profile: fetched.behavior_profile,
             fetched_at: SystemTime::now(),
             domain: domain.to_string(),
         };

src/tls_front/emulator.rs

@@ -3,7 +3,7 @@ use crate::protocol::constants::{
     TLS_RECORD_APPLICATION, TLS_RECORD_CHANGE_CIPHER, TLS_RECORD_HANDSHAKE, TLS_VERSION,
 };
 use crate::protocol::tls::{TLS_DIGEST_LEN, TLS_DIGEST_POS, gen_fake_x25519_key};
-use crate::tls_front::types::{CachedTlsData, ParsedCertificateInfo};
+use crate::tls_front::types::{CachedTlsData, ParsedCertificateInfo, TlsProfileSource};
 
 const MIN_APP_DATA: usize = 64;
 const MAX_APP_DATA: usize = 16640; // RFC 8446 §5.2 allows up to 2^14 + 256
@@ -108,14 +108,12 @@ pub fn build_emulated_server_hello(
 ) -> Vec<u8> {
     // --- ServerHello ---
     let mut extensions = Vec::new();
-    // KeyShare (x25519)
     let key = gen_fake_x25519_key(rng);
-    extensions.extend_from_slice(&0x0033u16.to_be_bytes()); // key_share
-    extensions.extend_from_slice(&(2 + 2 + 32u16).to_be_bytes()); // len
-    extensions.extend_from_slice(&0x001du16.to_be_bytes()); // X25519
+    extensions.extend_from_slice(&0x0033u16.to_be_bytes());
+    extensions.extend_from_slice(&(2 + 2 + 32u16).to_be_bytes());
+    extensions.extend_from_slice(&0x001du16.to_be_bytes());
     extensions.extend_from_slice(&(32u16).to_be_bytes());
     extensions.extend_from_slice(&key);
-    // supported_versions (TLS1.3)
     extensions.extend_from_slice(&0x002bu16.to_be_bytes());
     extensions.extend_from_slice(&(2u16).to_be_bytes());
     extensions.extend_from_slice(&0x0304u16.to_be_bytes());
@@ -128,7 +126,6 @@ pub fn build_emulated_server_hello(
         extensions.push(alpn_proto.len() as u8);
         extensions.extend_from_slice(alpn_proto);
     }
-
     let extensions_len = extensions.len() as u16;
 
     let body_len = 2 + // version
@@ -173,11 +170,22 @@ pub fn build_emulated_server_hello(
     ];
 
     // --- ApplicationData (fake encrypted records) ---
-    // Use the same number and sizes of ApplicationData records as the cached server.
-    let mut sizes = cached.app_data_records_sizes.clone();
-    if sizes.is_empty() {
-        sizes.push(cached.total_app_data_len.max(1024));
-    }
+    let sizes = match cached.behavior_profile.source {
+        TlsProfileSource::Raw | TlsProfileSource::Merged => cached
+            .app_data_records_sizes
+            .first()
+            .copied()
+            .or_else(|| cached.behavior_profile.app_data_record_sizes.first().copied())
+            .map(|size| vec![size])
+            .unwrap_or_else(|| vec![cached.total_app_data_len.max(1024)]),
+        _ => {
+            let mut sizes = cached.app_data_records_sizes.clone();
+            if sizes.is_empty() {
+                sizes.push(cached.total_app_data_len.max(1024));
+            }
+            sizes
+        }
+    };
     let mut sizes = jitter_and_clamp_sizes(&sizes, rng);
     let compact_payload = cached
         .cert_info
@@ -269,7 +277,9 @@ pub fn build_emulated_server_hello(
 mod tests {
     use std::time::SystemTime;
 
-    use crate::tls_front::types::{CachedTlsData, ParsedServerHello, TlsCertPayload};
+    use crate::tls_front::types::{
+        CachedTlsData, ParsedServerHello, TlsBehaviorProfile, TlsCertPayload, TlsProfileSource,
+    };
 
     use super::build_emulated_server_hello;
     use crate::crypto::SecureRandom;
@@ -300,6 +310,7 @@ mod tests {
             cert_payload,
             app_data_records_sizes: vec![64],
             total_app_data_len: 64,
+            behavior_profile: TlsBehaviorProfile::default(),
             fetched_at: SystemTime::now(),
             domain: "example.com".to_string(),
         }
@@ -385,4 +396,34 @@ mod tests {
         let payload = first_app_data_payload(&response);
         assert!(payload.starts_with(b"CN=example.com"));
     }
+
+    #[test]
+    fn test_build_emulated_server_hello_ignores_tail_records_for_raw_profile() {
+        let mut cached = make_cached(None);
+        cached.app_data_records_sizes = vec![27, 3905, 537, 69];
+        cached.total_app_data_len = 4538;
+        cached.behavior_profile.source = TlsProfileSource::Merged;
+        cached.behavior_profile.app_data_record_sizes = vec![27, 3905, 537];
+        cached.behavior_profile.ticket_record_sizes = vec![69];
+
+        let rng = SecureRandom::new();
+        let response = build_emulated_server_hello(
+            b"secret",
+            &[0x12; 32],
+            &[0x34; 16],
+            &cached,
+            false,
+            &rng,
+            None,
+            0,
+        );
+
+        let hello_len = u16::from_be_bytes([response[3], response[4]]) as usize;
+        let ccs_start = 5 + hello_len;
+        let app_start = ccs_start + 6;
+        let app_len = u16::from_be_bytes([response[app_start + 3], response[app_start + 4]]) as usize;
+
+        assert_eq!(response[app_start], TLS_RECORD_APPLICATION);
+        assert_eq!(app_start + 5 + app_len, response.len());
+    }
 }

src/tls_front/fetcher.rs

@@ -21,14 +21,18 @@ use x509_parser::certificate::X509Certificate;
 
 use crate::crypto::SecureRandom;
 use crate::network::dns_overrides::resolve_socket_addr;
-use crate::protocol::constants::{TLS_RECORD_APPLICATION, TLS_RECORD_HANDSHAKE};
+use crate::protocol::constants::{
+    TLS_RECORD_APPLICATION, TLS_RECORD_CHANGE_CIPHER, TLS_RECORD_HANDSHAKE,
+};
 use crate::transport::proxy_protocol::{ProxyProtocolV1Builder, ProxyProtocolV2Builder};
 use crate::tls_front::types::{
     ParsedCertificateInfo,
     ParsedServerHello,
+    TlsBehaviorProfile,
     TlsCertPayload,
     TlsExtension,
     TlsFetchResult,
+    TlsProfileSource,
 };
 
 /// No-op verifier: accept any certificate (we only need lengths and metadata).
@@ -282,6 +286,41 @@ fn parse_server_hello(body: &[u8]) -> Option<ParsedServerHello> {
     })
 }
 
+fn derive_behavior_profile(records: &[(u8, Vec<u8>)]) -> TlsBehaviorProfile {
+    let mut change_cipher_spec_count = 0u8;
+    let mut app_data_record_sizes = Vec::new();
+
+    for (record_type, body) in records {
+        match *record_type {
+            TLS_RECORD_CHANGE_CIPHER => {
+                change_cipher_spec_count = change_cipher_spec_count.saturating_add(1);
+            }
+            TLS_RECORD_APPLICATION => {
+                app_data_record_sizes.push(body.len());
+            }
+            _ => {}
+        }
+    }
+
+    let mut ticket_record_sizes = Vec::new();
+    while app_data_record_sizes
+        .last()
+        .is_some_and(|size| *size <= 256 && ticket_record_sizes.len() < 2)
+    {
+        if let Some(size) = app_data_record_sizes.pop() {
+            ticket_record_sizes.push(size);
+        }
+    }
+    ticket_record_sizes.reverse();
+
+    TlsBehaviorProfile {
+        change_cipher_spec_count: change_cipher_spec_count.max(1),
+        app_data_record_sizes,
+        ticket_record_sizes,
+        source: TlsProfileSource::Raw,
+    }
+}
+
 fn parse_cert_info(certs: &[CertificateDer<'static>]) -> Option<ParsedCertificateInfo> {
     let first = certs.first()?;
     let (_rem, cert) = X509Certificate::from_der(first.as_ref()).ok()?;
@@ -443,39 +482,50 @@ where
     .await??;
 
     let mut records = Vec::new();
-    // Read up to 4 records: ServerHello, CCS, and up to two ApplicationData.
-    for _ in 0..4 {
+    let mut app_records_seen = 0usize;
+    // Read a bounded encrypted flight: ServerHello, CCS, certificate-like data,
+    // and a small number of ticket-like tail records.
+    for _ in 0..8 {
         match timeout(connect_timeout, read_tls_record(&mut stream)).await {
-            Ok(Ok(rec)) => records.push(rec),
+            Ok(Ok(rec)) => {
+                if rec.0 == TLS_RECORD_APPLICATION {
+                    app_records_seen += 1;
+                }
+                records.push(rec);
+            }
             Ok(Err(e)) => return Err(e),
             Err(_) => break,
         }
-        if records.len() >= 3 && records.iter().any(|(t, _)| *t == TLS_RECORD_APPLICATION) {
+        if app_records_seen >= 4 {
             break;
         }
     }
 
-    let mut app_sizes = Vec::new();
     let mut server_hello = None;
     for (t, body) in &records {
         if *t == TLS_RECORD_HANDSHAKE && server_hello.is_none() {
             server_hello = parse_server_hello(body);
-        } else if *t == TLS_RECORD_APPLICATION {
-            app_sizes.push(body.len());
         }
     }
 
     let parsed = server_hello.ok_or_else(|| anyhow!("ServerHello not received"))?;
+    let behavior_profile = derive_behavior_profile(&records);
+    let mut app_sizes = behavior_profile.app_data_record_sizes.clone();
+    app_sizes.extend_from_slice(&behavior_profile.ticket_record_sizes);
     let total_app_data_len = app_sizes.iter().sum::<usize>().max(1024);
+    let app_data_records_sizes = behavior_profile
+        .app_data_record_sizes
+        .first()
+        .copied()
+        .or_else(|| behavior_profile.ticket_record_sizes.first().copied())
+        .map(|size| vec![size])
+        .unwrap_or_else(|| vec![total_app_data_len]);
 
     Ok(TlsFetchResult {
         server_hello_parsed: parsed,
-        app_data_records_sizes: if app_sizes.is_empty() {
-            vec![total_app_data_len]
-        } else {
-            app_sizes
-        },
+        app_data_records_sizes,
         total_app_data_len,
+        behavior_profile,
         cert_info: None,
         cert_payload: None,
     })
@@ -608,6 +658,12 @@ where
         server_hello_parsed: parsed,
         app_data_records_sizes: app_data_records_sizes.clone(),
         total_app_data_len: app_data_records_sizes.iter().sum(),
+        behavior_profile: TlsBehaviorProfile {
+            change_cipher_spec_count: 1,
+            app_data_record_sizes: app_data_records_sizes,
+            ticket_record_sizes: Vec::new(),
+            source: TlsProfileSource::Rustls,
+        },
         cert_info,
         cert_payload,
     })
@@ -706,6 +762,7 @@ pub async fn fetch_real_tls(
             if let Some(mut raw) = raw_result {
                 raw.cert_info = rustls_result.cert_info;
                 raw.cert_payload = rustls_result.cert_payload;
+                raw.behavior_profile.source = TlsProfileSource::Merged;
                 debug!(sni = %sni, "Fetched TLS metadata via raw probe + rustls cert chain");
                 Ok(raw)
             } else {
@@ -725,7 +782,11 @@ pub async fn fetch_real_tls(
 
 #[cfg(test)]
 mod tests {
-    use super::encode_tls13_certificate_message;
+    use super::{derive_behavior_profile, encode_tls13_certificate_message};
+    use crate::protocol::constants::{
+        TLS_RECORD_APPLICATION, TLS_RECORD_CHANGE_CIPHER, TLS_RECORD_HANDSHAKE,
+    };
+    use crate::tls_front::types::TlsProfileSource;
 
     fn read_u24(bytes: &[u8]) -> usize {
         ((bytes[0] as usize) << 16) | ((bytes[1] as usize) << 8) | (bytes[2] as usize)
@@ -753,4 +814,20 @@ mod tests {
     fn test_encode_tls13_certificate_message_empty_chain() {
         assert!(encode_tls13_certificate_message(&[]).is_none());
     }
+
+    #[test]
+    fn test_derive_behavior_profile_splits_ticket_like_tail_records() {
+        let profile = derive_behavior_profile(&[
+            (TLS_RECORD_HANDSHAKE, vec![0u8; 90]),
+            (TLS_RECORD_CHANGE_CIPHER, vec![0x01]),
+            (TLS_RECORD_APPLICATION, vec![0u8; 1400]),
+            (TLS_RECORD_APPLICATION, vec![0u8; 220]),
+            (TLS_RECORD_APPLICATION, vec![0u8; 180]),
+        ]);
+
+        assert_eq!(profile.change_cipher_spec_count, 1);
+        assert_eq!(profile.app_data_record_sizes, vec![1400]);
+        assert_eq!(profile.ticket_record_sizes, vec![220, 180]);
+        assert_eq!(profile.source, TlsProfileSource::Raw);
+    }
 }

src/tls_front/types.rs

@@ -39,6 +39,53 @@ pub struct TlsCertPayload {
     pub certificate_message: Vec<u8>,
 }
 
+/// Provenance of the cached TLS behavior profile.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum TlsProfileSource {
+    /// Built from hardcoded defaults or legacy cache entries.
+    #[default]
+    Default,
+    /// Derived from raw TLS record capture only.
+    Raw,
+    /// Derived from rustls-only metadata fallback.
+    Rustls,
+    /// Merged from raw TLS capture and rustls certificate metadata.
+    Merged,
+}
+
+/// Coarse-grained TLS response behavior captured per SNI.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TlsBehaviorProfile {
+    /// Number of ChangeCipherSpec records observed before encrypted flight.
+    #[serde(default = "default_change_cipher_spec_count")]
+    pub change_cipher_spec_count: u8,
+    /// Sizes of the primary encrypted flight records carrying cert-like payload.
+    #[serde(default)]
+    pub app_data_record_sizes: Vec<usize>,
+    /// Sizes of small tail ApplicationData records that look like tickets.
+    #[serde(default)]
+    pub ticket_record_sizes: Vec<usize>,
+    /// Source of this behavior profile.
+    #[serde(default)]
+    pub source: TlsProfileSource,
+}
+
+fn default_change_cipher_spec_count() -> u8 {
+    1
+}
+
+impl Default for TlsBehaviorProfile {
+    fn default() -> Self {
+        Self {
+            change_cipher_spec_count: default_change_cipher_spec_count(),
+            app_data_record_sizes: Vec::new(),
+            ticket_record_sizes: Vec::new(),
+            source: TlsProfileSource::Default,
+        }
+    }
+}
+
 /// Cached data per SNI used by the emulator.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct CachedTlsData {
@@ -48,6 +95,8 @@ pub struct CachedTlsData {
     pub cert_payload: Option<TlsCertPayload>,
     pub app_data_records_sizes: Vec<usize>,
     pub total_app_data_len: usize,
+    #[serde(default)]
+    pub behavior_profile: TlsBehaviorProfile,
     #[serde(default = "now_system_time", skip_serializing, skip_deserializing)]
     pub fetched_at: SystemTime,
     pub domain: String,
@@ -63,6 +112,40 @@ pub struct TlsFetchResult {
     pub server_hello_parsed: ParsedServerHello,
     pub app_data_records_sizes: Vec<usize>,
     pub total_app_data_len: usize,
+    #[serde(default)]
+    pub behavior_profile: TlsBehaviorProfile,
     pub cert_info: Option<ParsedCertificateInfo>,
     pub cert_payload: Option<TlsCertPayload>,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cached_tls_data_deserializes_without_behavior_profile() {
+        let json = r#"
+        {
+            "server_hello_template": {
+                "version": [3, 3],
+                "random": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+                "session_id": [],
+                "cipher_suite": [19, 1],
+                "compression": 0,
+                "extensions": []
+            },
+            "cert_info": null,
+            "cert_payload": null,
+            "app_data_records_sizes": [1024],
+            "total_app_data_len": 1024,
+            "domain": "example.com"
+        }
+        "#;
+
+        let cached: CachedTlsData = serde_json::from_str(json).unwrap();
+        assert_eq!(cached.behavior_profile.change_cipher_spec_count, 1);
+        assert!(cached.behavior_profile.app_data_record_sizes.is_empty());
+        assert!(cached.behavior_profile.ticket_record_sizes.is_empty());
+        assert_eq!(cached.behavior_profile.source, TlsProfileSource::Default);
+    }
+}

src/transport/middle_proxy/config_updater.rs

@@ -15,6 +15,7 @@ use crate::error::Result;
 use super::MePool;
 use super::rotation::{MeReinitTrigger, enqueue_reinit_trigger};
 use super::secret::download_proxy_secret_with_max_len;
+use super::selftest::record_timeskew_sample;
 use std::time::SystemTime;
 
 async fn retry_fetch(url: &str) -> Option<ProxyConfigData> {
@@ -109,6 +110,7 @@ pub async fn fetch_proxy_config_with_raw(url: &str) -> Result<(ProxyConfigData,
         })
     {
         let skew_secs = skew.as_secs();
+        record_timeskew_sample("proxy_config_date_header", skew_secs);
         if skew_secs > 60 {
             warn!(skew_secs, "Time skew >60s detected from fetch_proxy_config Date header");
         } else if skew_secs > 30 {
@@ -296,6 +298,7 @@ async fn run_update_cycle(
     pool.update_runtime_reinit_policy(
         cfg.general.hardswap,
         cfg.general.me_pool_drain_ttl_secs,
+        cfg.general.me_pool_drain_threshold,
         cfg.general.effective_me_pool_force_close_secs(),
         cfg.general.me_pool_min_fresh_ratio,
         cfg.general.me_hardswap_warmup_delay_min_ms,
@@ -306,6 +309,8 @@ async fn run_update_cycle(
         cfg.general.me_bind_stale_ttl_secs,
         cfg.general.me_secret_atomic_snapshot,
         cfg.general.me_deterministic_writer_sort,
+        cfg.general.me_writer_pick_mode,
+        cfg.general.me_writer_pick_sample_size,
         cfg.general.me_single_endpoint_shadow_writers,
         cfg.general.me_single_endpoint_outage_mode_enabled,
         cfg.general.me_single_endpoint_outage_disable_quarantine,
@@ -325,6 +330,9 @@ async fn run_update_cycle(
         cfg.general.me_adaptive_floor_max_warm_writers_per_core,
         cfg.general.me_adaptive_floor_max_active_writers_global,
         cfg.general.me_adaptive_floor_max_warm_writers_global,
+        cfg.general.me_health_interval_ms_unhealthy,
+        cfg.general.me_health_interval_ms_healthy,
+        cfg.general.me_warn_rate_limit_ms,
     );
 
     let required_cfg_snapshots = cfg.general.me_config_stable_snapshots.max(1);
@@ -517,6 +525,7 @@ pub async fn me_config_updater(
                 pool.update_runtime_reinit_policy(
                     cfg.general.hardswap,
                     cfg.general.me_pool_drain_ttl_secs,
+                    cfg.general.me_pool_drain_threshold,
                     cfg.general.effective_me_pool_force_close_secs(),
                     cfg.general.me_pool_min_fresh_ratio,
                     cfg.general.me_hardswap_warmup_delay_min_ms,
@@ -527,6 +536,8 @@ pub async fn me_config_updater(
                     cfg.general.me_bind_stale_ttl_secs,
                     cfg.general.me_secret_atomic_snapshot,
                     cfg.general.me_deterministic_writer_sort,
+                    cfg.general.me_writer_pick_mode,
+                    cfg.general.me_writer_pick_sample_size,
                     cfg.general.me_single_endpoint_shadow_writers,
                     cfg.general.me_single_endpoint_outage_mode_enabled,
                     cfg.general.me_single_endpoint_outage_disable_quarantine,
@@ -546,6 +557,9 @@ pub async fn me_config_updater(
                     cfg.general.me_adaptive_floor_max_warm_writers_per_core,
                     cfg.general.me_adaptive_floor_max_active_writers_global,
                     cfg.general.me_adaptive_floor_max_warm_writers_global,
+                    cfg.general.me_health_interval_ms_unhealthy,
+                    cfg.general.me_health_interval_ms_healthy,
+                    cfg.general.me_warn_rate_limit_ms,
                 );
                 let new_secs = cfg.general.effective_update_every_secs().max(1);
                 if new_secs == update_every_secs {

src/transport/middle_proxy/handshake.rs

@@ -33,6 +33,7 @@ use super::codec::{
     cbc_decrypt_inplace, cbc_encrypt_padded, parse_handshake_flags, parse_nonce_payload,
     read_rpc_frame_plaintext, rpc_crc,
 };
+use super::selftest::{BndAddrStatus, BndPortStatus, record_bnd_status, record_upstream_bnd_status};
 use super::wire::{extract_ip_material, IpMaterial};
 use super::MePool;
 
@@ -58,6 +59,7 @@ impl KdfClientPortSource {
 pub(crate) struct HandshakeOutput {
     pub rd: ReadHalf<TcpStream>,
     pub wr: WriteHalf<TcpStream>,
+    pub source_ip: IpAddr,
     pub read_key: [u8; 32],
     pub read_iv: [u8; 16],
     pub write_key: [u8; 32],
@@ -131,6 +133,14 @@ impl MePool {
         )
     }
 
+    fn bnd_port_status(bound: Option<SocketAddr>) -> BndPortStatus {
+        match bound {
+            Some(addr) if addr.port() == 0 => BndPortStatus::Zero,
+            Some(_) => BndPortStatus::Ok,
+            None => BndPortStatus::Error,
+        }
+    }
+
     /// TCP connect with timeout + return RTT in milliseconds.
     pub(crate) async fn connect_tcp(
         &self,
@@ -190,10 +200,26 @@ impl MePool {
 
     fn configure_keepalive(stream: &TcpStream) -> std::io::Result<()> {
         let sock = SockRef::from(stream);
-        let ka = TcpKeepalive::new()
-            .with_time(Duration::from_secs(30))
-            .with_interval(Duration::from_secs(10))
-            .with_retries(3);
+        let ka = TcpKeepalive::new().with_time(Duration::from_secs(30));
+
+        // Mirror socket2 v0.5.10 target gate for with_retries(), the stricter method.
+        #[cfg(any(
+            target_os = "android",
+            target_os = "dragonfly",
+            target_os = "freebsd",
+            target_os = "fuchsia",
+            target_os = "illumos",
+            target_os = "ios",
+            target_os = "visionos",
+            target_os = "linux",
+            target_os = "macos",
+            target_os = "netbsd",
+            target_os = "tvos",
+            target_os = "watchos",
+            target_os = "cygwin",
+        ))]
+        let ka = ka.with_interval(Duration::from_secs(10)).with_retries(3);
+
         sock.set_tcp_keepalive(&ka)?;
         sock.set_keepalive(true)?;
         Ok(())
@@ -239,7 +265,27 @@ impl MePool {
             IpFamily::V6
         };
         let is_socks_route = Self::is_socks_route(upstream_egress);
+        let raw_socks_bound_addr = if is_socks_route {
+            upstream_egress.and_then(|info| info.socks_bound_addr)
+        } else {
+            None
+        };
         let socks_bound_addr = Self::select_socks_bound_addr(family, upstream_egress);
+        let bnd_addr_status = if !is_socks_route {
+            BndAddrStatus::Error
+        } else if raw_socks_bound_addr.is_some() && socks_bound_addr.is_none() {
+            BndAddrStatus::Bogon
+        } else if socks_bound_addr.is_some() {
+            BndAddrStatus::Ok
+        } else {
+            BndAddrStatus::Error
+        };
+        let bnd_port_status = if is_socks_route {
+            Self::bnd_port_status(raw_socks_bound_addr)
+        } else {
+            BndPortStatus::Error
+        };
+        record_bnd_status(bnd_addr_status, bnd_port_status, raw_socks_bound_addr);
         let reflected = if let Some(bound) = socks_bound_addr {
             Some(bound)
         } else if is_socks_route {
@@ -270,6 +316,18 @@ impl MePool {
 
         let local_addr_nat = self.translate_our_addr_with_reflection(local_addr, reflected);
         let peer_addr_nat = SocketAddr::new(self.translate_ip_for_nat(peer_addr.ip()), peer_addr.port());
+        if let Some(upstream_info) = upstream_egress {
+            let client_ip_for_kdf = socks_bound_addr
+                .map(|value| value.ip())
+                .unwrap_or(local_addr_nat.ip());
+            record_upstream_bnd_status(
+                upstream_info.upstream_id,
+                bnd_addr_status,
+                bnd_port_status,
+                raw_socks_bound_addr,
+                Some(client_ip_for_kdf),
+            );
+        }
         let (mut rd, mut wr) = tokio::io::split(stream);
 
         let my_nonce: [u8; 16] = rng.bytes(16).try_into().unwrap();
@@ -632,6 +690,7 @@ impl MePool {
         Ok(HandshakeOutput {
             rd,
             wr,
+            source_ip: local_addr_nat.ip(),
             read_key: rk,
             read_iv,
             write_key: wk,
@@ -656,3 +715,66 @@ fn hex_dump(data: &[u8]) -> String {
     }
     out
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::ErrorKind;
+    use tokio::net::{TcpListener, TcpStream};
+
+    #[tokio::test]
+    async fn test_configure_keepalive_loopback() {
+        let listener = match TcpListener::bind("127.0.0.1:0").await {
+            Ok(listener) => listener,
+            Err(error) if error.kind() == ErrorKind::PermissionDenied => return,
+            Err(error) => panic!("bind failed: {error}"),
+        };
+
+        let addr = match listener.local_addr() {
+            Ok(addr) => addr,
+            Err(error) => panic!("local_addr failed: {error}"),
+        };
+
+        let stream = match TcpStream::connect(addr).await {
+            Ok(stream) => stream,
+            Err(error) if error.kind() == ErrorKind::PermissionDenied => return,
+            Err(error) => panic!("connect failed: {error}"),
+        };
+
+        if let Err(error) = MePool::configure_keepalive(&stream) {
+            if error.kind() == ErrorKind::PermissionDenied {
+                return;
+            }
+            panic!("configure_keepalive failed: {error}");
+        }
+    }
+
+    #[test]
+    #[cfg(target_os = "openbsd")]
+    fn test_openbsd_keepalive_cfg_path_compiles() {
+        let _ka = TcpKeepalive::new().with_time(Duration::from_secs(30));
+    }
+
+    #[test]
+    #[cfg(any(
+        target_os = "android",
+        target_os = "dragonfly",
+        target_os = "freebsd",
+        target_os = "fuchsia",
+        target_os = "illumos",
+        target_os = "ios",
+        target_os = "visionos",
+        target_os = "linux",
+        target_os = "macos",
+        target_os = "netbsd",
+        target_os = "tvos",
+        target_os = "watchos",
+        target_os = "cygwin",
+    ))]
+    fn test_retry_keepalive_cfg_path_compiles() {
+        let _ka = TcpKeepalive::new()
+            .with_time(Duration::from_secs(30))
+            .with_interval(Duration::from_secs(10))
+            .with_retries(3);
+    }
+}

src/transport/middle_proxy/health.rs

@@ -13,7 +13,6 @@ use crate::network::IpFamily;
 
 use super::MePool;
 
-const HEALTH_INTERVAL_SECS: u64 = 1;
 const JITTER_FRAC_NUM: u64 = 2; // jitter up to 50% of backoff
 #[allow(dead_code)]
 const MAX_CONCURRENT_PER_DC_DEFAULT: usize = 1;
@@ -26,6 +25,9 @@ const HEALTH_RECONNECT_BUDGET_PER_CORE: usize = 2;
 const HEALTH_RECONNECT_BUDGET_PER_DC: usize = 1;
 const HEALTH_RECONNECT_BUDGET_MIN: usize = 4;
 const HEALTH_RECONNECT_BUDGET_MAX: usize = 128;
+const HEALTH_DRAIN_CLOSE_BUDGET_PER_CORE: usize = 16;
+const HEALTH_DRAIN_CLOSE_BUDGET_MIN: usize = 16;
+const HEALTH_DRAIN_CLOSE_BUDGET_MAX: usize = 256;
 
 #[derive(Debug, Clone)]
 struct DcFloorPlanEntry {
@@ -62,11 +64,19 @@ pub async fn me_health_monitor(pool: Arc<MePool>, rng: Arc<SecureRandom>, _min_c
     let mut idle_refresh_next_attempt: HashMap<(i32, IpFamily), Instant> = HashMap::new();
     let mut adaptive_idle_since: HashMap<(i32, IpFamily), Instant> = HashMap::new();
     let mut adaptive_recover_until: HashMap<(i32, IpFamily), Instant> = HashMap::new();
+    let mut floor_warn_next_allowed: HashMap<(i32, IpFamily), Instant> = HashMap::new();
+    let mut drain_warn_next_allowed: HashMap<u64, Instant> = HashMap::new();
+    let mut degraded_interval = true;
     loop {
-        tokio::time::sleep(Duration::from_secs(HEALTH_INTERVAL_SECS)).await;
+        let interval = if degraded_interval {
+            pool.health_interval_unhealthy()
+        } else {
+            pool.health_interval_healthy()
+        };
+        tokio::time::sleep(interval).await;
         pool.prune_closed_writers().await;
-        reap_draining_writers(&pool).await;
-        check_family(
+        reap_draining_writers(&pool, &mut drain_warn_next_allowed).await;
+        let v4_degraded = check_family(
             IpFamily::V4,
             &pool,
             &rng,
@@ -80,9 +90,10 @@ pub async fn me_health_monitor(pool: Arc<MePool>, rng: Arc<SecureRandom>, _min_c
             &mut idle_refresh_next_attempt,
             &mut adaptive_idle_since,
             &mut adaptive_recover_until,
+            &mut floor_warn_next_allowed,
         )
         .await;
-        check_family(
+        let v6_degraded = check_family(
             IpFamily::V6,
             &pool,
             &rng,
@@ -96,31 +107,172 @@ pub async fn me_health_monitor(pool: Arc<MePool>, rng: Arc<SecureRandom>, _min_c
             &mut idle_refresh_next_attempt,
             &mut adaptive_idle_since,
             &mut adaptive_recover_until,
+            &mut floor_warn_next_allowed,
         )
         .await;
+        degraded_interval = v4_degraded || v6_degraded;
     }
 }
 
-async fn reap_draining_writers(pool: &Arc<MePool>) {
+pub(super) async fn reap_draining_writers(
+    pool: &Arc<MePool>,
+    warn_next_allowed: &mut HashMap<u64, Instant>,
+) {
     let now_epoch_secs = MePool::now_epoch_secs();
+    let now = Instant::now();
+    let drain_ttl_secs = pool.me_pool_drain_ttl_secs.load(std::sync::atomic::Ordering::Relaxed);
+    let drain_threshold = pool
+        .me_pool_drain_threshold
+        .load(std::sync::atomic::Ordering::Relaxed);
     let writers = pool.writers.read().await.clone();
+    let activity = pool.registry.writer_activity_snapshot().await;
+    let mut draining_writers = Vec::new();
+    let mut empty_writer_ids = Vec::<u64>::new();
+    let mut force_close_writer_ids = Vec::<u64>::new();
     for writer in writers {
         if !writer.draining.load(std::sync::atomic::Ordering::Relaxed) {
             continue;
         }
-        if pool.registry.is_writer_empty(writer.id).await {
-            pool.remove_writer_and_close_clients(writer.id).await;
+        if activity
+            .bound_clients_by_writer
+            .get(&writer.id)
+            .copied()
+            .unwrap_or(0)
+            == 0
+        {
+            empty_writer_ids.push(writer.id);
             continue;
         }
+        draining_writers.push(writer);
+    }
+
+    if drain_threshold > 0 && draining_writers.len() > drain_threshold as usize {
+        draining_writers.sort_by(|left, right| {
+            let left_started = left
+                .draining_started_at_epoch_secs
+                .load(std::sync::atomic::Ordering::Relaxed);
+            let right_started = right
+                .draining_started_at_epoch_secs
+                .load(std::sync::atomic::Ordering::Relaxed);
+            left_started
+                .cmp(&right_started)
+                .then_with(|| left.created_at.cmp(&right.created_at))
+                .then_with(|| left.id.cmp(&right.id))
+        });
+        let overflow = draining_writers.len().saturating_sub(drain_threshold as usize);
+        warn!(
+            draining_writers = draining_writers.len(),
+            me_pool_drain_threshold = drain_threshold,
+            removing_writers = overflow,
+            "ME draining writer threshold exceeded, force-closing oldest draining writers"
+        );
+        for writer in draining_writers.drain(..overflow) {
+            force_close_writer_ids.push(writer.id);
+        }
+    }
+
+    let mut active_draining_writer_ids = HashSet::with_capacity(draining_writers.len());
+    for writer in draining_writers {
+        active_draining_writer_ids.insert(writer.id);
+        let drain_started_at_epoch_secs = writer
+            .draining_started_at_epoch_secs
+            .load(std::sync::atomic::Ordering::Relaxed);
+        if drain_ttl_secs > 0
+            && drain_started_at_epoch_secs != 0
+            && now_epoch_secs.saturating_sub(drain_started_at_epoch_secs) > drain_ttl_secs
+            && should_emit_writer_warn(
+                warn_next_allowed,
+                writer.id,
+                now,
+                pool.warn_rate_limit_duration(),
+            )
+        {
+            warn!(
+                writer_id = writer.id,
+                writer_dc = writer.writer_dc,
+                endpoint = %writer.addr,
+                generation = writer.generation,
+                drain_ttl_secs,
+                force_close_secs = pool.me_pool_force_close_secs.load(std::sync::atomic::Ordering::Relaxed),
+                allow_drain_fallback = writer.allow_drain_fallback.load(std::sync::atomic::Ordering::Relaxed),
+                "ME draining writer remains non-empty past drain TTL"
+            );
+        }
         let deadline_epoch_secs = writer
             .drain_deadline_epoch_secs
             .load(std::sync::atomic::Ordering::Relaxed);
         if deadline_epoch_secs != 0 && now_epoch_secs >= deadline_epoch_secs {
             warn!(writer_id = writer.id, "Drain timeout, force-closing");
-            pool.stats.increment_pool_force_close_total();
-            pool.remove_writer_and_close_clients(writer.id).await;
+            force_close_writer_ids.push(writer.id);
+            active_draining_writer_ids.remove(&writer.id);
         }
     }
+
+    warn_next_allowed.retain(|writer_id, _| active_draining_writer_ids.contains(writer_id));
+
+    let close_budget = health_drain_close_budget();
+    let requested_force_close = force_close_writer_ids.len();
+    let requested_empty_close = empty_writer_ids.len();
+    let requested_close_total = requested_force_close.saturating_add(requested_empty_close);
+    let mut closed_writer_ids = HashSet::<u64>::new();
+    let mut closed_total = 0usize;
+    for writer_id in force_close_writer_ids {
+        if closed_total >= close_budget {
+            break;
+        }
+        if !closed_writer_ids.insert(writer_id) {
+            continue;
+        }
+        pool.stats.increment_pool_force_close_total();
+        pool.remove_writer_and_close_clients(writer_id).await;
+        closed_total = closed_total.saturating_add(1);
+    }
+    for writer_id in empty_writer_ids {
+        if closed_total >= close_budget {
+            break;
+        }
+        if !closed_writer_ids.insert(writer_id) {
+            continue;
+        }
+        pool.remove_writer_and_close_clients(writer_id).await;
+        closed_total = closed_total.saturating_add(1);
+    }
+
+    let pending_close_total = requested_close_total.saturating_sub(closed_total);
+    if pending_close_total > 0 {
+        warn!(
+            close_budget,
+            closed_total,
+            pending_close_total,
+            "ME draining close backlog deferred to next health cycle"
+        );
+    }
+}
+
+pub(super) fn health_drain_close_budget() -> usize {
+    let cpu_cores = std::thread::available_parallelism()
+        .map(std::num::NonZeroUsize::get)
+        .unwrap_or(1);
+    cpu_cores
+        .saturating_mul(HEALTH_DRAIN_CLOSE_BUDGET_PER_CORE)
+        .clamp(HEALTH_DRAIN_CLOSE_BUDGET_MIN, HEALTH_DRAIN_CLOSE_BUDGET_MAX)
+}
+
+fn should_emit_writer_warn(
+    next_allowed: &mut HashMap<u64, Instant>,
+    writer_id: u64,
+    now: Instant,
+    cooldown: Duration,
+) -> bool {
+    let Some(ready_at) = next_allowed.get(&writer_id).copied() else {
+        next_allowed.insert(writer_id, now + cooldown);
+        return true;
+    };
+    if now >= ready_at {
+        next_allowed.insert(writer_id, now + cooldown);
+        return true;
+    }
+    false
 }
 
 async fn check_family(
@@ -137,15 +289,18 @@ async fn check_family(
     idle_refresh_next_attempt: &mut HashMap<(i32, IpFamily), Instant>,
     adaptive_idle_since: &mut HashMap<(i32, IpFamily), Instant>,
     adaptive_recover_until: &mut HashMap<(i32, IpFamily), Instant>,
-) {
+    floor_warn_next_allowed: &mut HashMap<(i32, IpFamily), Instant>,
+) -> bool {
     let enabled = match family {
         IpFamily::V4 => pool.decision.ipv4_me,
         IpFamily::V6 => pool.decision.ipv6_me,
     };
     if !enabled {
-        return;
+        return false;
     }
 
+    let mut family_degraded = false;
+
     let mut dc_endpoints = HashMap::<i32, Vec<SocketAddr>>::new();
     let map_guard = match family {
         IpFamily::V4 => pool.proxy_map_v4.read().await,
@@ -234,6 +389,7 @@ async fn check_family(
             .sum::<usize>();
 
         if endpoints.len() == 1 && pool.single_endpoint_outage_mode_enabled() && alive == 0 {
+            family_degraded = true;
             if single_endpoint_outage.insert(key) {
                 pool.stats.increment_me_single_endpoint_outage_enter_total();
                 warn!(
@@ -310,6 +466,7 @@ async fn check_family(
             continue;
         }
         let missing = required - alive;
+        family_degraded = true;
 
         let now = Instant::now();
         if reconnect_budget == 0 {
@@ -438,15 +595,23 @@ async fn check_family(
                 + Duration::from_millis(rand::rng().random_range(0..=jitter.max(1)));
             next_attempt.insert(key, now + wait);
             if pool.is_runtime_ready() {
-                warn!(
-                    dc = %dc,
-                    ?family,
-                    alive = now_alive,
-                    required,
-                    endpoint_count = endpoints.len(),
-                    backoff_ms = next_ms,
-                    "DC writer floor is below required level, scheduled reconnect"
-                );
+                let warn_cooldown = pool.warn_rate_limit_duration();
+                if should_emit_rate_limited_warn(
+                    floor_warn_next_allowed,
+                    key,
+                    now,
+                    warn_cooldown,
+                ) {
+                    warn!(
+                        dc = %dc,
+                        ?family,
+                        alive = now_alive,
+                        required,
+                        endpoint_count = endpoints.len(),
+                        backoff_ms = next_ms,
+                        "DC writer floor is below required level, scheduled reconnect"
+                    );
+                }
             } else {
                 info!(
                     dc = %dc,
@@ -463,6 +628,8 @@ async fn check_family(
             *v = v.saturating_sub(1);
         }
     }
+
+    family_degraded
 }
 
 fn health_reconnect_budget(pool: &Arc<MePool>, dc_groups: usize) -> usize {
@@ -474,6 +641,23 @@ fn health_reconnect_budget(pool: &Arc<MePool>, dc_groups: usize) -> usize {
         .clamp(HEALTH_RECONNECT_BUDGET_MIN, HEALTH_RECONNECT_BUDGET_MAX)
 }
 
+fn should_emit_rate_limited_warn(
+    next_allowed: &mut HashMap<(i32, IpFamily), Instant>,
+    key: (i32, IpFamily),
+    now: Instant,
+    cooldown: Duration,
+) -> bool {
+    let Some(ready_at) = next_allowed.get(&key).copied() else {
+        next_allowed.insert(key, now + cooldown);
+        return true;
+    };
+    if now >= ready_at {
+        next_allowed.insert(key, now + cooldown);
+        return true;
+    }
+    false
+}
+
 fn adaptive_floor_class_min(
     pool: &Arc<MePool>,
     endpoint_count: usize,
@@ -1181,3 +1365,190 @@ async fn maybe_rotate_single_endpoint_shadow(
         "Single-endpoint shadow writer rotated"
     );
 }
+
+#[cfg(test)]
+mod tests {
+    use std::collections::HashMap;
+    use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU32, AtomicU64, Ordering};
+    use std::time::{Duration, Instant};
+
+    use tokio::sync::mpsc;
+    use tokio_util::sync::CancellationToken;
+
+    use super::reap_draining_writers;
+    use crate::config::{GeneralConfig, MeRouteNoWriterMode, MeSocksKdfPolicy, MeWriterPickMode};
+    use crate::crypto::SecureRandom;
+    use crate::network::probe::NetworkDecision;
+    use crate::stats::Stats;
+    use crate::transport::middle_proxy::codec::WriterCommand;
+    use crate::transport::middle_proxy::pool::{MePool, MeWriter, WriterContour};
+    use crate::transport::middle_proxy::registry::ConnMeta;
+
+    async fn make_pool(me_pool_drain_threshold: u64) -> Arc<MePool> {
+        let general = GeneralConfig {
+            me_pool_drain_threshold,
+            ..GeneralConfig::default()
+        };
+        MePool::new(
+            None,
+            vec![1u8; 32],
+            None,
+            false,
+            None,
+            Vec::new(),
+            1,
+            None,
+            12,
+            1200,
+            HashMap::new(),
+            HashMap::new(),
+            None,
+            NetworkDecision::default(),
+            None,
+            Arc::new(SecureRandom::new()),
+            Arc::new(Stats::default()),
+            general.me_keepalive_enabled,
+            general.me_keepalive_interval_secs,
+            general.me_keepalive_jitter_secs,
+            general.me_keepalive_payload_random,
+            general.rpc_proxy_req_every,
+            general.me_warmup_stagger_enabled,
+            general.me_warmup_step_delay_ms,
+            general.me_warmup_step_jitter_ms,
+            general.me_reconnect_max_concurrent_per_dc,
+            general.me_reconnect_backoff_base_ms,
+            general.me_reconnect_backoff_cap_ms,
+            general.me_reconnect_fast_retry_count,
+            general.me_single_endpoint_shadow_writers,
+            general.me_single_endpoint_outage_mode_enabled,
+            general.me_single_endpoint_outage_disable_quarantine,
+            general.me_single_endpoint_outage_backoff_min_ms,
+            general.me_single_endpoint_outage_backoff_max_ms,
+            general.me_single_endpoint_shadow_rotate_every_secs,
+            general.me_floor_mode,
+            general.me_adaptive_floor_idle_secs,
+            general.me_adaptive_floor_min_writers_single_endpoint,
+            general.me_adaptive_floor_min_writers_multi_endpoint,
+            general.me_adaptive_floor_recover_grace_secs,
+            general.me_adaptive_floor_writers_per_core_total,
+            general.me_adaptive_floor_cpu_cores_override,
+            general.me_adaptive_floor_max_extra_writers_single_per_core,
+            general.me_adaptive_floor_max_extra_writers_multi_per_core,
+            general.me_adaptive_floor_max_active_writers_per_core,
+            general.me_adaptive_floor_max_warm_writers_per_core,
+            general.me_adaptive_floor_max_active_writers_global,
+            general.me_adaptive_floor_max_warm_writers_global,
+            general.hardswap,
+            general.me_pool_drain_ttl_secs,
+            general.me_pool_drain_threshold,
+            general.effective_me_pool_force_close_secs(),
+            general.me_pool_min_fresh_ratio,
+            general.me_hardswap_warmup_delay_min_ms,
+            general.me_hardswap_warmup_delay_max_ms,
+            general.me_hardswap_warmup_extra_passes,
+            general.me_hardswap_warmup_pass_backoff_base_ms,
+            general.me_bind_stale_mode,
+            general.me_bind_stale_ttl_secs,
+            general.me_secret_atomic_snapshot,
+            general.me_deterministic_writer_sort,
+            MeWriterPickMode::default(),
+            general.me_writer_pick_sample_size,
+            MeSocksKdfPolicy::default(),
+            general.me_writer_cmd_channel_capacity,
+            general.me_route_channel_capacity,
+            general.me_route_backpressure_base_timeout_ms,
+            general.me_route_backpressure_high_timeout_ms,
+            general.me_route_backpressure_high_watermark_pct,
+            general.me_reader_route_data_wait_ms,
+            general.me_health_interval_ms_unhealthy,
+            general.me_health_interval_ms_healthy,
+            general.me_warn_rate_limit_ms,
+            MeRouteNoWriterMode::default(),
+            general.me_route_no_writer_wait_ms,
+            general.me_route_inline_recovery_attempts,
+            general.me_route_inline_recovery_wait_ms,
+        )
+    }
+
+    async fn insert_draining_writer(
+        pool: &Arc<MePool>,
+        writer_id: u64,
+        drain_started_at_epoch_secs: u64,
+    ) -> u64 {
+        let (conn_id, _rx) = pool.registry.register().await;
+        let (tx, _writer_rx) = mpsc::channel::<WriterCommand>(8);
+        let writer = MeWriter {
+            id: writer_id,
+            addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 4000 + writer_id as u16),
+            source_ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
+            writer_dc: 2,
+            generation: 1,
+            contour: Arc::new(AtomicU8::new(WriterContour::Draining.as_u8())),
+            created_at: Instant::now() - Duration::from_secs(writer_id),
+            tx: tx.clone(),
+            cancel: CancellationToken::new(),
+            degraded: Arc::new(AtomicBool::new(false)),
+            rtt_ema_ms_x10: Arc::new(AtomicU32::new(0)),
+            draining: Arc::new(AtomicBool::new(true)),
+            draining_started_at_epoch_secs: Arc::new(AtomicU64::new(drain_started_at_epoch_secs)),
+            drain_deadline_epoch_secs: Arc::new(AtomicU64::new(0)),
+            allow_drain_fallback: Arc::new(AtomicBool::new(false)),
+        };
+        pool.writers.write().await.push(writer);
+        pool.registry.register_writer(writer_id, tx).await;
+        pool.conn_count.fetch_add(1, Ordering::Relaxed);
+        assert!(
+            pool.registry
+                .bind_writer(
+                    conn_id,
+                    writer_id,
+                    ConnMeta {
+                        target_dc: 2,
+                        client_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 6000),
+                        our_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 443),
+                        proto_flags: 0,
+                    },
+                )
+                .await
+        );
+        conn_id
+    }
+
+    #[tokio::test]
+    async fn reap_draining_writers_force_closes_oldest_over_threshold() {
+        let pool = make_pool(2).await;
+        let now_epoch_secs = MePool::now_epoch_secs();
+        let conn_a = insert_draining_writer(&pool, 10, now_epoch_secs.saturating_sub(30)).await;
+        let conn_b = insert_draining_writer(&pool, 20, now_epoch_secs.saturating_sub(20)).await;
+        let conn_c = insert_draining_writer(&pool, 30, now_epoch_secs.saturating_sub(10)).await;
+        let mut warn_next_allowed = HashMap::new();
+
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+        let writer_ids: Vec<u64> = pool.writers.read().await.iter().map(|writer| writer.id).collect();
+        assert_eq!(writer_ids, vec![20, 30]);
+        assert!(pool.registry.get_writer(conn_a).await.is_none());
+        assert_eq!(pool.registry.get_writer(conn_b).await.unwrap().writer_id, 20);
+        assert_eq!(pool.registry.get_writer(conn_c).await.unwrap().writer_id, 30);
+    }
+
+    #[tokio::test]
+    async fn reap_draining_writers_keeps_timeout_only_behavior_when_threshold_disabled() {
+        let pool = make_pool(0).await;
+        let now_epoch_secs = MePool::now_epoch_secs();
+        let conn_a = insert_draining_writer(&pool, 10, now_epoch_secs.saturating_sub(30)).await;
+        let conn_b = insert_draining_writer(&pool, 20, now_epoch_secs.saturating_sub(20)).await;
+        let conn_c = insert_draining_writer(&pool, 30, now_epoch_secs.saturating_sub(10)).await;
+        let mut warn_next_allowed = HashMap::new();
+
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+        let writer_ids: Vec<u64> = pool.writers.read().await.iter().map(|writer| writer.id).collect();
+        assert_eq!(writer_ids, vec![10, 20, 30]);
+        assert_eq!(pool.registry.get_writer(conn_a).await.unwrap().writer_id, 10);
+        assert_eq!(pool.registry.get_writer(conn_b).await.unwrap().writer_id, 20);
+        assert_eq!(pool.registry.get_writer(conn_c).await.unwrap().writer_id, 30);
+    }
+}

src/transport/middle_proxy/health_adversarial_tests.rs

@@ -0,0 +1,437 @@
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU32, AtomicU64, Ordering};
+use std::time::{Duration, Instant};
+
+use tokio::sync::mpsc;
+use tokio_util::sync::CancellationToken;
+
+use super::codec::WriterCommand;
+use super::health::{health_drain_close_budget, reap_draining_writers};
+use super::pool::{MePool, MeWriter, WriterContour};
+use super::registry::ConnMeta;
+use super::me_health_monitor;
+use crate::config::{GeneralConfig, MeRouteNoWriterMode, MeSocksKdfPolicy, MeWriterPickMode};
+use crate::crypto::SecureRandom;
+use crate::network::probe::NetworkDecision;
+use crate::stats::Stats;
+
+async fn make_pool(
+    me_pool_drain_threshold: u64,
+    me_health_interval_ms_unhealthy: u64,
+    me_health_interval_ms_healthy: u64,
+) -> (Arc<MePool>, Arc<SecureRandom>) {
+    let general = GeneralConfig {
+        me_pool_drain_threshold,
+        me_health_interval_ms_unhealthy,
+        me_health_interval_ms_healthy,
+        ..GeneralConfig::default()
+    };
+
+    let rng = Arc::new(SecureRandom::new());
+    let pool = MePool::new(
+        None,
+        vec![1u8; 32],
+        None,
+        false,
+        None,
+        Vec::new(),
+        1,
+        None,
+        12,
+        1200,
+        HashMap::new(),
+        HashMap::new(),
+        None,
+        NetworkDecision::default(),
+        None,
+        rng.clone(),
+        Arc::new(Stats::default()),
+        general.me_keepalive_enabled,
+        general.me_keepalive_interval_secs,
+        general.me_keepalive_jitter_secs,
+        general.me_keepalive_payload_random,
+        general.rpc_proxy_req_every,
+        general.me_warmup_stagger_enabled,
+        general.me_warmup_step_delay_ms,
+        general.me_warmup_step_jitter_ms,
+        general.me_reconnect_max_concurrent_per_dc,
+        general.me_reconnect_backoff_base_ms,
+        general.me_reconnect_backoff_cap_ms,
+        general.me_reconnect_fast_retry_count,
+        general.me_single_endpoint_shadow_writers,
+        general.me_single_endpoint_outage_mode_enabled,
+        general.me_single_endpoint_outage_disable_quarantine,
+        general.me_single_endpoint_outage_backoff_min_ms,
+        general.me_single_endpoint_outage_backoff_max_ms,
+        general.me_single_endpoint_shadow_rotate_every_secs,
+        general.me_floor_mode,
+        general.me_adaptive_floor_idle_secs,
+        general.me_adaptive_floor_min_writers_single_endpoint,
+        general.me_adaptive_floor_min_writers_multi_endpoint,
+        general.me_adaptive_floor_recover_grace_secs,
+        general.me_adaptive_floor_writers_per_core_total,
+        general.me_adaptive_floor_cpu_cores_override,
+        general.me_adaptive_floor_max_extra_writers_single_per_core,
+        general.me_adaptive_floor_max_extra_writers_multi_per_core,
+        general.me_adaptive_floor_max_active_writers_per_core,
+        general.me_adaptive_floor_max_warm_writers_per_core,
+        general.me_adaptive_floor_max_active_writers_global,
+        general.me_adaptive_floor_max_warm_writers_global,
+        general.hardswap,
+        general.me_pool_drain_ttl_secs,
+        general.me_pool_drain_threshold,
+        general.effective_me_pool_force_close_secs(),
+        general.me_pool_min_fresh_ratio,
+        general.me_hardswap_warmup_delay_min_ms,
+        general.me_hardswap_warmup_delay_max_ms,
+        general.me_hardswap_warmup_extra_passes,
+        general.me_hardswap_warmup_pass_backoff_base_ms,
+        general.me_bind_stale_mode,
+        general.me_bind_stale_ttl_secs,
+        general.me_secret_atomic_snapshot,
+        general.me_deterministic_writer_sort,
+        MeWriterPickMode::default(),
+        general.me_writer_pick_sample_size,
+        MeSocksKdfPolicy::default(),
+        general.me_writer_cmd_channel_capacity,
+        general.me_route_channel_capacity,
+        general.me_route_backpressure_base_timeout_ms,
+        general.me_route_backpressure_high_timeout_ms,
+        general.me_route_backpressure_high_watermark_pct,
+        general.me_reader_route_data_wait_ms,
+        general.me_health_interval_ms_unhealthy,
+        general.me_health_interval_ms_healthy,
+        general.me_warn_rate_limit_ms,
+        MeRouteNoWriterMode::default(),
+        general.me_route_no_writer_wait_ms,
+        general.me_route_inline_recovery_attempts,
+        general.me_route_inline_recovery_wait_ms,
+    );
+
+    (pool, rng)
+}
+
+async fn insert_draining_writer(
+    pool: &Arc<MePool>,
+    writer_id: u64,
+    drain_started_at_epoch_secs: u64,
+    bound_clients: usize,
+    drain_deadline_epoch_secs: u64,
+) {
+    let (tx, _writer_rx) = mpsc::channel::<WriterCommand>(8);
+    let writer = MeWriter {
+        id: writer_id,
+        addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 6000 + writer_id as u16),
+        source_ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
+        writer_dc: 2,
+        generation: 1,
+        contour: Arc::new(AtomicU8::new(WriterContour::Draining.as_u8())),
+        created_at: Instant::now() - Duration::from_secs(writer_id),
+        tx: tx.clone(),
+        cancel: CancellationToken::new(),
+        degraded: Arc::new(AtomicBool::new(false)),
+        rtt_ema_ms_x10: Arc::new(AtomicU32::new(0)),
+        draining: Arc::new(AtomicBool::new(true)),
+        draining_started_at_epoch_secs: Arc::new(AtomicU64::new(drain_started_at_epoch_secs)),
+        drain_deadline_epoch_secs: Arc::new(AtomicU64::new(drain_deadline_epoch_secs)),
+        allow_drain_fallback: Arc::new(AtomicBool::new(false)),
+    };
+
+    pool.writers.write().await.push(writer);
+    pool.registry.register_writer(writer_id, tx).await;
+    pool.conn_count.fetch_add(1, Ordering::Relaxed);
+
+    for idx in 0..bound_clients {
+        let (conn_id, _rx) = pool.registry.register().await;
+        assert!(
+            pool.registry
+                .bind_writer(
+                    conn_id,
+                    writer_id,
+                    ConnMeta {
+                        target_dc: 2,
+                        client_addr: SocketAddr::new(
+                            IpAddr::V4(Ipv4Addr::LOCALHOST),
+                            8000 + idx as u16,
+                        ),
+                        our_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 443),
+                        proto_flags: 0,
+                    },
+                )
+                .await
+        );
+    }
+}
+
+async fn writer_count(pool: &Arc<MePool>) -> usize {
+    pool.writers.read().await.len()
+}
+
+async fn sorted_writer_ids(pool: &Arc<MePool>) -> Vec<u64> {
+    let mut ids = pool
+        .writers
+        .read()
+        .await
+        .iter()
+        .map(|writer| writer.id)
+        .collect::<Vec<_>>();
+    ids.sort_unstable();
+    ids
+}
+
+#[tokio::test]
+async fn reap_draining_writers_clears_warn_state_when_pool_empty() {
+    let (pool, _rng) = make_pool(128, 1, 1).await;
+    let mut warn_next_allowed = HashMap::new();
+    warn_next_allowed.insert(11, Instant::now() + Duration::from_secs(5));
+    warn_next_allowed.insert(22, Instant::now() + Duration::from_secs(5));
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert!(warn_next_allowed.is_empty());
+}
+
+#[tokio::test]
+async fn reap_draining_writers_respects_threshold_across_multiple_overflow_cycles() {
+    let threshold = 3u64;
+    let (pool, _rng) = make_pool(threshold, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+
+    for writer_id in 1..=60u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(600).saturating_add(writer_id),
+            1,
+            0,
+        )
+        .await;
+    }
+
+    let mut warn_next_allowed = HashMap::new();
+    for _ in 0..64 {
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        if writer_count(&pool).await <= threshold as usize {
+            break;
+        }
+    }
+
+    assert_eq!(writer_count(&pool).await, threshold as usize);
+    assert_eq!(sorted_writer_ids(&pool).await, vec![58, 59, 60]);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_handles_large_empty_writer_population() {
+    let (pool, _rng) = make_pool(128, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let total = health_drain_close_budget().saturating_mul(3).saturating_add(27);
+
+    for writer_id in 1..=total as u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(120),
+            0,
+            0,
+        )
+        .await;
+    }
+
+    let mut warn_next_allowed = HashMap::new();
+    for _ in 0..24 {
+        if writer_count(&pool).await == 0 {
+            break;
+        }
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    }
+
+    assert_eq!(writer_count(&pool).await, 0);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_processes_mass_deadline_expiry_without_unbounded_growth() {
+    let (pool, _rng) = make_pool(128, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let total = health_drain_close_budget().saturating_mul(4).saturating_add(31);
+
+    for writer_id in 1..=total as u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(180),
+            1,
+            now_epoch_secs.saturating_sub(1),
+        )
+        .await;
+    }
+
+    let mut warn_next_allowed = HashMap::new();
+    for _ in 0..40 {
+        if writer_count(&pool).await == 0 {
+            break;
+        }
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    }
+
+    assert_eq!(writer_count(&pool).await, 0);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_maintains_warn_state_subset_property_under_bulk_churn() {
+    let (pool, _rng) = make_pool(128, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let mut warn_next_allowed = HashMap::new();
+
+    for wave in 0..40u64 {
+        for offset in 0..8u64 {
+            insert_draining_writer(
+                &pool,
+                wave * 100 + offset,
+                now_epoch_secs.saturating_sub(400 + offset),
+                1,
+                0,
+            )
+            .await;
+        }
+
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        assert!(warn_next_allowed.len() <= writer_count(&pool).await);
+
+        let ids = sorted_writer_ids(&pool).await;
+        for writer_id in ids.into_iter().take(3) {
+            let _ = pool.remove_writer_and_close_clients(writer_id).await;
+        }
+
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        assert!(warn_next_allowed.len() <= writer_count(&pool).await);
+    }
+}
+
+#[tokio::test]
+async fn reap_draining_writers_budgeted_cleanup_never_increases_pool_size() {
+    let (pool, _rng) = make_pool(5, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+
+    for writer_id in 1..=200u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(240).saturating_add(writer_id),
+            1,
+            0,
+        )
+        .await;
+    }
+
+    let mut warn_next_allowed = HashMap::new();
+    let mut previous = writer_count(&pool).await;
+    for _ in 0..32 {
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        let current = writer_count(&pool).await;
+        assert!(current <= previous);
+        previous = current;
+    }
+}
+
+#[tokio::test]
+async fn me_health_monitor_converges_to_threshold_under_live_injection_churn() {
+    let threshold = 7u64;
+    let (pool, rng) = make_pool(threshold, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+
+    for writer_id in 1..=40u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(300).saturating_add(writer_id),
+            1,
+            0,
+        )
+        .await;
+    }
+
+    let monitor = tokio::spawn(me_health_monitor(pool.clone(), rng, 0));
+
+    for wave in 0..8u64 {
+        for offset in 0..10u64 {
+            insert_draining_writer(
+                &pool,
+                1000 + wave * 100 + offset,
+                now_epoch_secs.saturating_sub(120).saturating_add(offset),
+                1,
+                0,
+            )
+            .await;
+        }
+        tokio::time::sleep(Duration::from_millis(5)).await;
+    }
+
+    tokio::time::sleep(Duration::from_millis(120)).await;
+    monitor.abort();
+    let _ = monitor.await;
+
+    assert!(writer_count(&pool).await <= threshold as usize);
+}
+
+#[tokio::test]
+async fn me_health_monitor_drains_deadline_storm_with_budgeted_progress() {
+    let (pool, rng) = make_pool(128, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+
+    for writer_id in 1..=220u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(120),
+            1,
+            now_epoch_secs.saturating_sub(1),
+        )
+        .await;
+    }
+
+    let monitor = tokio::spawn(me_health_monitor(pool.clone(), rng, 0));
+    tokio::time::sleep(Duration::from_millis(120)).await;
+    monitor.abort();
+    let _ = monitor.await;
+
+    assert_eq!(writer_count(&pool).await, 0);
+}
+
+#[tokio::test]
+async fn me_health_monitor_eliminates_mixed_empty_and_deadline_backlog() {
+    let threshold = 12u64;
+    let (pool, rng) = make_pool(threshold, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+
+    for writer_id in 1..=180u64 {
+        let bound_clients = if writer_id % 3 == 0 { 0 } else { 1 };
+        let deadline = if writer_id % 2 == 0 {
+            now_epoch_secs.saturating_sub(1)
+        } else {
+            0
+        };
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(250).saturating_add(writer_id),
+            bound_clients,
+            deadline,
+        )
+        .await;
+    }
+
+    let monitor = tokio::spawn(me_health_monitor(pool.clone(), rng, 0));
+    tokio::time::sleep(Duration::from_millis(140)).await;
+    monitor.abort();
+    let _ = monitor.await;
+
+    assert!(writer_count(&pool).await <= threshold as usize);
+}
+
+#[test]
+fn health_drain_close_budget_is_within_expected_bounds() {
+    let budget = health_drain_close_budget();
+    assert!((16..=256).contains(&budget));
+}

src/transport/middle_proxy/health_integration_tests.rs

@@ -0,0 +1,227 @@
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU32, AtomicU64, Ordering};
+use std::time::{Duration, Instant};
+
+use tokio::sync::mpsc;
+use tokio_util::sync::CancellationToken;
+
+use super::codec::WriterCommand;
+use super::health::health_drain_close_budget;
+use super::pool::{MePool, MeWriter, WriterContour};
+use super::registry::ConnMeta;
+use super::me_health_monitor;
+use crate::config::{GeneralConfig, MeRouteNoWriterMode, MeSocksKdfPolicy, MeWriterPickMode};
+use crate::crypto::SecureRandom;
+use crate::network::probe::NetworkDecision;
+use crate::stats::Stats;
+
+async fn make_pool(
+    me_pool_drain_threshold: u64,
+    me_health_interval_ms_unhealthy: u64,
+    me_health_interval_ms_healthy: u64,
+) -> (Arc<MePool>, Arc<SecureRandom>) {
+    let general = GeneralConfig {
+        me_pool_drain_threshold,
+        me_health_interval_ms_unhealthy,
+        me_health_interval_ms_healthy,
+        ..GeneralConfig::default()
+    };
+    let rng = Arc::new(SecureRandom::new());
+    let pool = MePool::new(
+        None,
+        vec![1u8; 32],
+        None,
+        false,
+        None,
+        Vec::new(),
+        1,
+        None,
+        12,
+        1200,
+        HashMap::new(),
+        HashMap::new(),
+        None,
+        NetworkDecision::default(),
+        None,
+        rng.clone(),
+        Arc::new(Stats::default()),
+        general.me_keepalive_enabled,
+        general.me_keepalive_interval_secs,
+        general.me_keepalive_jitter_secs,
+        general.me_keepalive_payload_random,
+        general.rpc_proxy_req_every,
+        general.me_warmup_stagger_enabled,
+        general.me_warmup_step_delay_ms,
+        general.me_warmup_step_jitter_ms,
+        general.me_reconnect_max_concurrent_per_dc,
+        general.me_reconnect_backoff_base_ms,
+        general.me_reconnect_backoff_cap_ms,
+        general.me_reconnect_fast_retry_count,
+        general.me_single_endpoint_shadow_writers,
+        general.me_single_endpoint_outage_mode_enabled,
+        general.me_single_endpoint_outage_disable_quarantine,
+        general.me_single_endpoint_outage_backoff_min_ms,
+        general.me_single_endpoint_outage_backoff_max_ms,
+        general.me_single_endpoint_shadow_rotate_every_secs,
+        general.me_floor_mode,
+        general.me_adaptive_floor_idle_secs,
+        general.me_adaptive_floor_min_writers_single_endpoint,
+        general.me_adaptive_floor_min_writers_multi_endpoint,
+        general.me_adaptive_floor_recover_grace_secs,
+        general.me_adaptive_floor_writers_per_core_total,
+        general.me_adaptive_floor_cpu_cores_override,
+        general.me_adaptive_floor_max_extra_writers_single_per_core,
+        general.me_adaptive_floor_max_extra_writers_multi_per_core,
+        general.me_adaptive_floor_max_active_writers_per_core,
+        general.me_adaptive_floor_max_warm_writers_per_core,
+        general.me_adaptive_floor_max_active_writers_global,
+        general.me_adaptive_floor_max_warm_writers_global,
+        general.hardswap,
+        general.me_pool_drain_ttl_secs,
+        general.me_pool_drain_threshold,
+        general.effective_me_pool_force_close_secs(),
+        general.me_pool_min_fresh_ratio,
+        general.me_hardswap_warmup_delay_min_ms,
+        general.me_hardswap_warmup_delay_max_ms,
+        general.me_hardswap_warmup_extra_passes,
+        general.me_hardswap_warmup_pass_backoff_base_ms,
+        general.me_bind_stale_mode,
+        general.me_bind_stale_ttl_secs,
+        general.me_secret_atomic_snapshot,
+        general.me_deterministic_writer_sort,
+        MeWriterPickMode::default(),
+        general.me_writer_pick_sample_size,
+        MeSocksKdfPolicy::default(),
+        general.me_writer_cmd_channel_capacity,
+        general.me_route_channel_capacity,
+        general.me_route_backpressure_base_timeout_ms,
+        general.me_route_backpressure_high_timeout_ms,
+        general.me_route_backpressure_high_watermark_pct,
+        general.me_reader_route_data_wait_ms,
+        general.me_health_interval_ms_unhealthy,
+        general.me_health_interval_ms_healthy,
+        general.me_warn_rate_limit_ms,
+        MeRouteNoWriterMode::default(),
+        general.me_route_no_writer_wait_ms,
+        general.me_route_inline_recovery_attempts,
+        general.me_route_inline_recovery_wait_ms,
+    );
+    (pool, rng)
+}
+
+async fn insert_draining_writer(
+    pool: &Arc<MePool>,
+    writer_id: u64,
+    drain_started_at_epoch_secs: u64,
+    bound_clients: usize,
+    drain_deadline_epoch_secs: u64,
+) {
+    let (tx, _writer_rx) = mpsc::channel::<WriterCommand>(8);
+    let writer = MeWriter {
+        id: writer_id,
+        addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 5500 + writer_id as u16),
+        source_ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
+        writer_dc: 2,
+        generation: 1,
+        contour: Arc::new(AtomicU8::new(WriterContour::Draining.as_u8())),
+        created_at: Instant::now() - Duration::from_secs(writer_id),
+        tx: tx.clone(),
+        cancel: CancellationToken::new(),
+        degraded: Arc::new(AtomicBool::new(false)),
+        rtt_ema_ms_x10: Arc::new(AtomicU32::new(0)),
+        draining: Arc::new(AtomicBool::new(true)),
+        draining_started_at_epoch_secs: Arc::new(AtomicU64::new(drain_started_at_epoch_secs)),
+        drain_deadline_epoch_secs: Arc::new(AtomicU64::new(drain_deadline_epoch_secs)),
+        allow_drain_fallback: Arc::new(AtomicBool::new(false)),
+    };
+    pool.writers.write().await.push(writer);
+    pool.registry.register_writer(writer_id, tx).await;
+    pool.conn_count.fetch_add(1, Ordering::Relaxed);
+    for idx in 0..bound_clients {
+        let (conn_id, _rx) = pool.registry.register().await;
+        assert!(
+            pool.registry
+                .bind_writer(
+                    conn_id,
+                    writer_id,
+                    ConnMeta {
+                        target_dc: 2,
+                        client_addr: SocketAddr::new(
+                            IpAddr::V4(Ipv4Addr::LOCALHOST),
+                            7200 + idx as u16,
+                        ),
+                        our_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 443),
+                        proto_flags: 0,
+                    },
+                )
+                .await
+        );
+    }
+}
+
+#[tokio::test]
+async fn me_health_monitor_drains_expired_backlog_over_multiple_cycles() {
+    let (pool, rng) = make_pool(128, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let writer_total = health_drain_close_budget().saturating_mul(2).saturating_add(9);
+    for writer_id in 1..=writer_total as u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(120),
+            1,
+            now_epoch_secs.saturating_sub(1),
+        )
+        .await;
+    }
+
+    let monitor = tokio::spawn(me_health_monitor(pool.clone(), rng, 0));
+    tokio::time::sleep(Duration::from_millis(60)).await;
+    monitor.abort();
+    let _ = monitor.await;
+
+    assert!(pool.writers.read().await.is_empty());
+}
+
+#[tokio::test]
+async fn me_health_monitor_cleans_empty_draining_writers_without_force_close() {
+    let (pool, rng) = make_pool(128, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    for writer_id in 1..=24u64 {
+        insert_draining_writer(&pool, writer_id, now_epoch_secs.saturating_sub(60), 0, 0).await;
+    }
+
+    let monitor = tokio::spawn(me_health_monitor(pool.clone(), rng, 0));
+    tokio::time::sleep(Duration::from_millis(30)).await;
+    monitor.abort();
+    let _ = monitor.await;
+
+    assert!(pool.writers.read().await.is_empty());
+}
+
+#[tokio::test]
+async fn me_health_monitor_converges_retry_like_threshold_backlog_to_empty() {
+    let threshold = 4u64;
+    let (pool, rng) = make_pool(threshold, 1, 1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let writer_total = threshold as usize + health_drain_close_budget().saturating_add(11);
+    for writer_id in 1..=writer_total as u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(300).saturating_add(writer_id),
+            1,
+            0,
+        )
+        .await;
+    }
+
+    let monitor = tokio::spawn(me_health_monitor(pool.clone(), rng, 0));
+    tokio::time::sleep(Duration::from_millis(60)).await;
+    monitor.abort();
+    let _ = monitor.await;
+
+    assert!(pool.writers.read().await.is_empty());
+}

src/transport/middle_proxy/health_regression_tests.rs

@@ -0,0 +1,462 @@
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU32, AtomicU64, Ordering};
+use std::time::{Duration, Instant};
+
+use tokio::sync::mpsc;
+use tokio_util::sync::CancellationToken;
+
+use super::codec::WriterCommand;
+use super::health::{health_drain_close_budget, reap_draining_writers};
+use super::pool::{MePool, MeWriter, WriterContour};
+use super::registry::ConnMeta;
+use crate::config::{GeneralConfig, MeRouteNoWriterMode, MeSocksKdfPolicy, MeWriterPickMode};
+use crate::crypto::SecureRandom;
+use crate::network::probe::NetworkDecision;
+use crate::stats::Stats;
+
+async fn make_pool(me_pool_drain_threshold: u64) -> Arc<MePool> {
+    let general = GeneralConfig {
+        me_pool_drain_threshold,
+        ..GeneralConfig::default()
+    };
+
+    MePool::new(
+        None,
+        vec![1u8; 32],
+        None,
+        false,
+        None,
+        Vec::new(),
+        1,
+        None,
+        12,
+        1200,
+        HashMap::new(),
+        HashMap::new(),
+        None,
+        NetworkDecision::default(),
+        None,
+        Arc::new(SecureRandom::new()),
+        Arc::new(Stats::default()),
+        general.me_keepalive_enabled,
+        general.me_keepalive_interval_secs,
+        general.me_keepalive_jitter_secs,
+        general.me_keepalive_payload_random,
+        general.rpc_proxy_req_every,
+        general.me_warmup_stagger_enabled,
+        general.me_warmup_step_delay_ms,
+        general.me_warmup_step_jitter_ms,
+        general.me_reconnect_max_concurrent_per_dc,
+        general.me_reconnect_backoff_base_ms,
+        general.me_reconnect_backoff_cap_ms,
+        general.me_reconnect_fast_retry_count,
+        general.me_single_endpoint_shadow_writers,
+        general.me_single_endpoint_outage_mode_enabled,
+        general.me_single_endpoint_outage_disable_quarantine,
+        general.me_single_endpoint_outage_backoff_min_ms,
+        general.me_single_endpoint_outage_backoff_max_ms,
+        general.me_single_endpoint_shadow_rotate_every_secs,
+        general.me_floor_mode,
+        general.me_adaptive_floor_idle_secs,
+        general.me_adaptive_floor_min_writers_single_endpoint,
+        general.me_adaptive_floor_min_writers_multi_endpoint,
+        general.me_adaptive_floor_recover_grace_secs,
+        general.me_adaptive_floor_writers_per_core_total,
+        general.me_adaptive_floor_cpu_cores_override,
+        general.me_adaptive_floor_max_extra_writers_single_per_core,
+        general.me_adaptive_floor_max_extra_writers_multi_per_core,
+        general.me_adaptive_floor_max_active_writers_per_core,
+        general.me_adaptive_floor_max_warm_writers_per_core,
+        general.me_adaptive_floor_max_active_writers_global,
+        general.me_adaptive_floor_max_warm_writers_global,
+        general.hardswap,
+        general.me_pool_drain_ttl_secs,
+        general.me_pool_drain_threshold,
+        general.effective_me_pool_force_close_secs(),
+        general.me_pool_min_fresh_ratio,
+        general.me_hardswap_warmup_delay_min_ms,
+        general.me_hardswap_warmup_delay_max_ms,
+        general.me_hardswap_warmup_extra_passes,
+        general.me_hardswap_warmup_pass_backoff_base_ms,
+        general.me_bind_stale_mode,
+        general.me_bind_stale_ttl_secs,
+        general.me_secret_atomic_snapshot,
+        general.me_deterministic_writer_sort,
+        MeWriterPickMode::default(),
+        general.me_writer_pick_sample_size,
+        MeSocksKdfPolicy::default(),
+        general.me_writer_cmd_channel_capacity,
+        general.me_route_channel_capacity,
+        general.me_route_backpressure_base_timeout_ms,
+        general.me_route_backpressure_high_timeout_ms,
+        general.me_route_backpressure_high_watermark_pct,
+        general.me_reader_route_data_wait_ms,
+        general.me_health_interval_ms_unhealthy,
+        general.me_health_interval_ms_healthy,
+        general.me_warn_rate_limit_ms,
+        MeRouteNoWriterMode::default(),
+        general.me_route_no_writer_wait_ms,
+        general.me_route_inline_recovery_attempts,
+        general.me_route_inline_recovery_wait_ms,
+    )
+}
+
+async fn insert_draining_writer(
+    pool: &Arc<MePool>,
+    writer_id: u64,
+    drain_started_at_epoch_secs: u64,
+    bound_clients: usize,
+    drain_deadline_epoch_secs: u64,
+) -> Vec<u64> {
+    let mut conn_ids = Vec::with_capacity(bound_clients);
+    let (tx, _writer_rx) = mpsc::channel::<WriterCommand>(8);
+    let writer = MeWriter {
+        id: writer_id,
+        addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 4500 + writer_id as u16),
+        source_ip: IpAddr::V4(Ipv4Addr::LOCALHOST),
+        writer_dc: 2,
+        generation: 1,
+        contour: Arc::new(AtomicU8::new(WriterContour::Draining.as_u8())),
+        created_at: Instant::now() - Duration::from_secs(writer_id),
+        tx: tx.clone(),
+        cancel: CancellationToken::new(),
+        degraded: Arc::new(AtomicBool::new(false)),
+        rtt_ema_ms_x10: Arc::new(AtomicU32::new(0)),
+        draining: Arc::new(AtomicBool::new(true)),
+        draining_started_at_epoch_secs: Arc::new(AtomicU64::new(drain_started_at_epoch_secs)),
+        drain_deadline_epoch_secs: Arc::new(AtomicU64::new(drain_deadline_epoch_secs)),
+        allow_drain_fallback: Arc::new(AtomicBool::new(false)),
+    };
+    pool.writers.write().await.push(writer);
+    pool.registry.register_writer(writer_id, tx).await;
+    pool.conn_count.fetch_add(1, Ordering::Relaxed);
+    for idx in 0..bound_clients {
+        let (conn_id, _rx) = pool.registry.register().await;
+        assert!(
+            pool.registry
+                .bind_writer(
+                    conn_id,
+                    writer_id,
+                    ConnMeta {
+                        target_dc: 2,
+                        client_addr: SocketAddr::new(
+                            IpAddr::V4(Ipv4Addr::LOCALHOST),
+                            6200 + idx as u16,
+                        ),
+                        our_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 443),
+                        proto_flags: 0,
+                    },
+                )
+                .await
+        );
+        conn_ids.push(conn_id);
+    }
+    conn_ids
+}
+
+async fn current_writer_ids(pool: &Arc<MePool>) -> Vec<u64> {
+    let mut writer_ids = pool
+        .writers
+        .read()
+        .await
+        .iter()
+        .map(|writer| writer.id)
+        .collect::<Vec<_>>();
+    writer_ids.sort_unstable();
+    writer_ids
+}
+
+#[tokio::test]
+async fn reap_draining_writers_drops_warn_state_for_removed_writer() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let conn_ids =
+        insert_draining_writer(&pool, 7, now_epoch_secs.saturating_sub(180), 1, 0).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    assert!(warn_next_allowed.contains_key(&7));
+
+    let _ = pool.remove_writer_and_close_clients(7).await;
+    assert!(pool.registry.get_writer(conn_ids[0]).await.is_none());
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    assert!(!warn_next_allowed.contains_key(&7));
+}
+
+#[tokio::test]
+async fn reap_draining_writers_removes_empty_draining_writers() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(&pool, 1, now_epoch_secs.saturating_sub(40), 0, 0).await;
+    insert_draining_writer(&pool, 2, now_epoch_secs.saturating_sub(30), 0, 0).await;
+    insert_draining_writer(&pool, 3, now_epoch_secs.saturating_sub(20), 1, 0).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert_eq!(current_writer_ids(&pool).await, vec![3]);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_overflow_closes_oldest_non_empty_writers() {
+    let pool = make_pool(2).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(&pool, 11, now_epoch_secs.saturating_sub(40), 1, 0).await;
+    insert_draining_writer(&pool, 22, now_epoch_secs.saturating_sub(30), 1, 0).await;
+    insert_draining_writer(&pool, 33, now_epoch_secs.saturating_sub(20), 1, 0).await;
+    insert_draining_writer(&pool, 44, now_epoch_secs.saturating_sub(10), 1, 0).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert_eq!(current_writer_ids(&pool).await, vec![33, 44]);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_deadline_force_close_applies_under_threshold() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(
+        &pool,
+        50,
+        now_epoch_secs.saturating_sub(15),
+        1,
+        now_epoch_secs.saturating_sub(1),
+    )
+    .await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert!(current_writer_ids(&pool).await.is_empty());
+}
+
+#[tokio::test]
+async fn reap_draining_writers_limits_closes_per_health_tick() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let close_budget = health_drain_close_budget();
+    let writer_total = close_budget.saturating_add(19);
+    for writer_id in 1..=writer_total as u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(20),
+            1,
+            now_epoch_secs.saturating_sub(1),
+        )
+        .await;
+    }
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert_eq!(pool.writers.read().await.len(), writer_total - close_budget);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_backlog_drains_across_ticks() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let close_budget = health_drain_close_budget();
+    let writer_total = close_budget.saturating_mul(2).saturating_add(7);
+    for writer_id in 1..=writer_total as u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(20),
+            1,
+            now_epoch_secs.saturating_sub(1),
+        )
+        .await;
+    }
+    let mut warn_next_allowed = HashMap::new();
+
+    for _ in 0..8 {
+        if pool.writers.read().await.is_empty() {
+            break;
+        }
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+    }
+
+    assert!(pool.writers.read().await.is_empty());
+}
+
+#[tokio::test]
+async fn reap_draining_writers_threshold_backlog_converges_to_threshold() {
+    let threshold = 5u64;
+    let pool = make_pool(threshold).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let close_budget = health_drain_close_budget();
+    let writer_total = threshold as usize + close_budget.saturating_add(12);
+    for writer_id in 1..=writer_total as u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(200).saturating_add(writer_id),
+            1,
+            0,
+        )
+        .await;
+    }
+    let mut warn_next_allowed = HashMap::new();
+
+    for _ in 0..16 {
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        if pool.writers.read().await.len() <= threshold as usize {
+            break;
+        }
+    }
+
+    assert_eq!(pool.writers.read().await.len(), threshold as usize);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_threshold_zero_preserves_non_expired_non_empty_writers() {
+    let pool = make_pool(0).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(&pool, 10, now_epoch_secs.saturating_sub(40), 1, 0).await;
+    insert_draining_writer(&pool, 20, now_epoch_secs.saturating_sub(30), 1, 0).await;
+    insert_draining_writer(&pool, 30, now_epoch_secs.saturating_sub(20), 1, 0).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert_eq!(current_writer_ids(&pool).await, vec![10, 20, 30]);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_prioritizes_force_close_before_empty_cleanup() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let close_budget = health_drain_close_budget();
+    for writer_id in 1..=close_budget as u64 {
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(20),
+            1,
+            now_epoch_secs.saturating_sub(1),
+        )
+        .await;
+    }
+    let empty_writer_id = close_budget as u64 + 1;
+    insert_draining_writer(&pool, empty_writer_id, now_epoch_secs.saturating_sub(20), 0, 0).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert_eq!(current_writer_ids(&pool).await, vec![empty_writer_id]);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_empty_cleanup_does_not_increment_force_close_metric() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(&pool, 1, now_epoch_secs.saturating_sub(60), 0, 0).await;
+    insert_draining_writer(&pool, 2, now_epoch_secs.saturating_sub(50), 0, 0).await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert!(current_writer_ids(&pool).await.is_empty());
+    assert_eq!(pool.stats.get_pool_force_close_total(), 0);
+}
+
+#[tokio::test]
+async fn reap_draining_writers_handles_duplicate_force_close_requests_for_same_writer() {
+    let pool = make_pool(1).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    insert_draining_writer(
+        &pool,
+        10,
+        now_epoch_secs.saturating_sub(30),
+        1,
+        now_epoch_secs.saturating_sub(1),
+    )
+    .await;
+    insert_draining_writer(
+        &pool,
+        20,
+        now_epoch_secs.saturating_sub(20),
+        1,
+        now_epoch_secs.saturating_sub(1),
+    )
+    .await;
+    let mut warn_next_allowed = HashMap::new();
+
+    reap_draining_writers(&pool, &mut warn_next_allowed).await;
+
+    assert!(current_writer_ids(&pool).await.is_empty());
+}
+
+#[tokio::test]
+async fn reap_draining_writers_warn_state_never_exceeds_live_draining_population_under_churn() {
+    let pool = make_pool(128).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let mut warn_next_allowed = HashMap::new();
+
+    for wave in 0..12u64 {
+        for offset in 0..9u64 {
+            insert_draining_writer(
+                &pool,
+                wave * 100 + offset,
+                now_epoch_secs.saturating_sub(120 + offset),
+                1,
+                0,
+            )
+            .await;
+        }
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        assert!(warn_next_allowed.len() <= pool.writers.read().await.len());
+
+        let existing_writer_ids = current_writer_ids(&pool).await;
+        for writer_id in existing_writer_ids.into_iter().take(4) {
+            let _ = pool.remove_writer_and_close_clients(writer_id).await;
+        }
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        assert!(warn_next_allowed.len() <= pool.writers.read().await.len());
+    }
+}
+
+#[tokio::test]
+async fn reap_draining_writers_mixed_backlog_converges_without_leaking_warn_state() {
+    let pool = make_pool(6).await;
+    let now_epoch_secs = MePool::now_epoch_secs();
+    let mut warn_next_allowed = HashMap::new();
+
+    for writer_id in 1..=18u64 {
+        let bound_clients = if writer_id % 3 == 0 { 0 } else { 1 };
+        let deadline = if writer_id % 2 == 0 {
+            now_epoch_secs.saturating_sub(1)
+        } else {
+            0
+        };
+        insert_draining_writer(
+            &pool,
+            writer_id,
+            now_epoch_secs.saturating_sub(300).saturating_add(writer_id),
+            bound_clients,
+            deadline,
+        )
+        .await;
+    }
+
+    for _ in 0..16 {
+        reap_draining_writers(&pool, &mut warn_next_allowed).await;
+        if pool.writers.read().await.len() <= 6 {
+            break;
+        }
+    }
+
+    assert!(pool.writers.read().await.len() <= 6);
+    assert!(warn_next_allowed.len() <= pool.writers.read().await.len());
+}
+
+#[test]
+fn general_config_default_drain_threshold_remains_enabled() {
+    assert_eq!(GeneralConfig::default().me_pool_drain_threshold, 128);
+}

src/transport/middle_proxy/mod.rs

@@ -18,8 +18,15 @@ mod registry;
 mod rotation;
 mod send;
 mod secret;
+mod selftest;
 mod wire;
 mod pool_status;
+#[cfg(test)]
+mod health_regression_tests;
+#[cfg(test)]
+mod health_integration_tests;
+#[cfg(test)]
+mod health_adversarial_tests;
 
 use bytes::Bytes;
 
@@ -37,6 +44,9 @@ pub use config_updater::{
     me_config_updater, save_proxy_config_cache,
 };
 pub use rotation::{MeReinitTrigger, me_reinit_scheduler, me_rotation_task};
+pub(crate) use selftest::{
+    bnd_snapshot, timeskew_snapshot, upstream_bnd_snapshots,
+};
 pub use wire::proto_flags_for_tag;
 
 #[derive(Debug)]

src/transport/middle_proxy/pool.rs

@@ -7,7 +7,9 @@ use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 use tokio::sync::{Mutex, Notify, RwLock, mpsc};
 use tokio_util::sync::CancellationToken;
 
-use crate::config::{MeBindStaleMode, MeFloorMode, MeRouteNoWriterMode, MeSocksKdfPolicy};
+use crate::config::{
+    MeBindStaleMode, MeFloorMode, MeRouteNoWriterMode, MeSocksKdfPolicy, MeWriterPickMode,
+};
 use crate::crypto::SecureRandom;
 use crate::network::IpFamily;
 use crate::network::probe::NetworkDecision;
@@ -32,6 +34,7 @@ pub(super) struct RefillEndpointKey {
 pub struct MeWriter {
     pub id: u64,
     pub addr: SocketAddr,
+    pub source_ip: IpAddr,
     pub writer_dc: i32,
     pub generation: u64,
     pub contour: Arc<AtomicU8>,
@@ -39,6 +42,7 @@ pub struct MeWriter {
     pub tx: mpsc::Sender<WriterCommand>,
     pub cancel: CancellationToken,
     pub degraded: Arc<AtomicBool>,
+    pub rtt_ema_ms_x10: Arc<AtomicU32>,
     pub draining: Arc<AtomicBool>,
     pub draining_started_at_epoch_secs: Arc<AtomicU64>,
     pub drain_deadline_epoch_secs: Arc<AtomicU64>,
@@ -103,6 +107,7 @@ pub struct MePool {
     pub(super) me_keepalive_jitter: Duration,
     pub(super) me_keepalive_payload_random: bool,
     pub(super) rpc_proxy_req_every_secs: AtomicU64,
+    pub(super) writer_cmd_channel_capacity: usize,
     pub(super) me_warmup_stagger_enabled: bool,
     pub(super) me_warmup_step_delay: Duration,
     pub(super) me_warmup_step_jitter: Duration,
@@ -166,6 +171,7 @@ pub struct MePool {
     pub(super) endpoint_quarantine: Arc<Mutex<HashMap<SocketAddr, Instant>>>,
     pub(super) kdf_material_fingerprint: Arc<RwLock<HashMap<SocketAddr, (u64, u16)>>>,
     pub(super) me_pool_drain_ttl_secs: AtomicU64,
+    pub(super) me_pool_drain_threshold: AtomicU64,
     pub(super) me_pool_force_close_secs: AtomicU64,
     pub(super) me_pool_min_fresh_ratio_permille: AtomicU32,
     pub(super) me_hardswap_warmup_delay_min_ms: AtomicU64,
@@ -176,13 +182,20 @@ pub struct MePool {
     pub(super) me_bind_stale_ttl_secs: AtomicU64,
     pub(super) secret_atomic_snapshot: AtomicBool,
     pub(super) me_deterministic_writer_sort: AtomicBool,
+    pub(super) me_writer_pick_mode: AtomicU8,
+    pub(super) me_writer_pick_sample_size: AtomicU8,
     pub(super) me_socks_kdf_policy: AtomicU8,
+    pub(super) me_reader_route_data_wait_ms: Arc<AtomicU64>,
     pub(super) me_route_no_writer_mode: AtomicU8,
     pub(super) me_route_no_writer_wait: Duration,
     pub(super) me_route_inline_recovery_attempts: u32,
     pub(super) me_route_inline_recovery_wait: Duration,
+    pub(super) me_health_interval_ms_unhealthy: AtomicU64,
+    pub(super) me_health_interval_ms_healthy: AtomicU64,
+    pub(super) me_warn_rate_limit_ms: AtomicU64,
     pub(super) runtime_ready: AtomicBool,
     pool_size: usize,
+    pub(super) preferred_endpoints_by_dc: Arc<RwLock<HashMap<i32, Vec<SocketAddr>>>>,
 }
 
 #[derive(Debug, Default)]
@@ -259,6 +272,7 @@ impl MePool {
         me_adaptive_floor_max_warm_writers_global: u32,
         hardswap: bool,
         me_pool_drain_ttl_secs: u64,
+        me_pool_drain_threshold: u64,
         me_pool_force_close_secs: u64,
         me_pool_min_fresh_ratio: f32,
         me_hardswap_warmup_delay_min_ms: u64,
@@ -269,17 +283,29 @@ impl MePool {
         me_bind_stale_ttl_secs: u64,
         me_secret_atomic_snapshot: bool,
         me_deterministic_writer_sort: bool,
+        me_writer_pick_mode: MeWriterPickMode,
+        me_writer_pick_sample_size: u8,
         me_socks_kdf_policy: MeSocksKdfPolicy,
+        me_writer_cmd_channel_capacity: usize,
+        me_route_channel_capacity: usize,
         me_route_backpressure_base_timeout_ms: u64,
         me_route_backpressure_high_timeout_ms: u64,
         me_route_backpressure_high_watermark_pct: u8,
+        me_reader_route_data_wait_ms: u64,
+        me_health_interval_ms_unhealthy: u64,
+        me_health_interval_ms_healthy: u64,
+        me_warn_rate_limit_ms: u64,
         me_route_no_writer_mode: MeRouteNoWriterMode,
         me_route_no_writer_wait_ms: u64,
         me_route_inline_recovery_attempts: u32,
         me_route_inline_recovery_wait_ms: u64,
     ) -> Arc<Self> {
         let endpoint_dc_map = Self::build_endpoint_dc_map_from_maps(&proxy_map_v4, &proxy_map_v6);
-        let registry = Arc::new(ConnRegistry::new());
+        let preferred_endpoints_by_dc =
+            Self::build_preferred_endpoints_by_dc(&decision, &proxy_map_v4, &proxy_map_v6);
+        let registry = Arc::new(ConnRegistry::with_route_channel_capacity(
+            me_route_channel_capacity,
+        ));
         registry.update_route_backpressure_policy(
             me_route_backpressure_base_timeout_ms,
             me_route_backpressure_high_timeout_ms,
@@ -326,6 +352,7 @@ impl MePool {
             me_keepalive_jitter: Duration::from_secs(me_keepalive_jitter_secs),
             me_keepalive_payload_random,
             rpc_proxy_req_every_secs: AtomicU64::new(rpc_proxy_req_every_secs),
+            writer_cmd_channel_capacity: me_writer_cmd_channel_capacity.max(1),
             me_warmup_stagger_enabled,
             me_warmup_step_delay: Duration::from_millis(me_warmup_step_delay_ms),
             me_warmup_step_jitter: Duration::from_millis(me_warmup_step_jitter_ms),
@@ -421,6 +448,7 @@ impl MePool {
             endpoint_quarantine: Arc::new(Mutex::new(HashMap::new())),
             kdf_material_fingerprint: Arc::new(RwLock::new(HashMap::new())),
             me_pool_drain_ttl_secs: AtomicU64::new(me_pool_drain_ttl_secs),
+            me_pool_drain_threshold: AtomicU64::new(me_pool_drain_threshold),
             me_pool_force_close_secs: AtomicU64::new(me_pool_force_close_secs),
             me_pool_min_fresh_ratio_permille: AtomicU32::new(Self::ratio_to_permille(
                 me_pool_min_fresh_ratio,
@@ -435,12 +463,19 @@ impl MePool {
             me_bind_stale_ttl_secs: AtomicU64::new(me_bind_stale_ttl_secs),
             secret_atomic_snapshot: AtomicBool::new(me_secret_atomic_snapshot),
             me_deterministic_writer_sort: AtomicBool::new(me_deterministic_writer_sort),
+            me_writer_pick_mode: AtomicU8::new(me_writer_pick_mode.as_u8()),
+            me_writer_pick_sample_size: AtomicU8::new(me_writer_pick_sample_size.clamp(2, 4)),
             me_socks_kdf_policy: AtomicU8::new(me_socks_kdf_policy.as_u8()),
+            me_reader_route_data_wait_ms: Arc::new(AtomicU64::new(me_reader_route_data_wait_ms)),
             me_route_no_writer_mode: AtomicU8::new(me_route_no_writer_mode.as_u8()),
             me_route_no_writer_wait: Duration::from_millis(me_route_no_writer_wait_ms),
             me_route_inline_recovery_attempts,
             me_route_inline_recovery_wait: Duration::from_millis(me_route_inline_recovery_wait_ms),
+            me_health_interval_ms_unhealthy: AtomicU64::new(me_health_interval_ms_unhealthy.max(1)),
+            me_health_interval_ms_healthy: AtomicU64::new(me_health_interval_ms_healthy.max(1)),
+            me_warn_rate_limit_ms: AtomicU64::new(me_warn_rate_limit_ms.max(1)),
             runtime_ready: AtomicBool::new(false),
+            preferred_endpoints_by_dc: Arc::new(RwLock::new(preferred_endpoints_by_dc)),
         })
     }
 
@@ -460,6 +495,7 @@ impl MePool {
         &self,
         hardswap: bool,
         drain_ttl_secs: u64,
+        pool_drain_threshold: u64,
         force_close_secs: u64,
         min_fresh_ratio: f32,
         hardswap_warmup_delay_min_ms: u64,
@@ -470,6 +506,8 @@ impl MePool {
         bind_stale_ttl_secs: u64,
         secret_atomic_snapshot: bool,
         deterministic_writer_sort: bool,
+        writer_pick_mode: MeWriterPickMode,
+        writer_pick_sample_size: u8,
         single_endpoint_shadow_writers: u8,
         single_endpoint_outage_mode_enabled: bool,
         single_endpoint_outage_disable_quarantine: bool,
@@ -489,10 +527,15 @@ impl MePool {
         adaptive_floor_max_warm_writers_per_core: u16,
         adaptive_floor_max_active_writers_global: u32,
         adaptive_floor_max_warm_writers_global: u32,
+        me_health_interval_ms_unhealthy: u64,
+        me_health_interval_ms_healthy: u64,
+        me_warn_rate_limit_ms: u64,
     ) {
         self.hardswap.store(hardswap, Ordering::Relaxed);
         self.me_pool_drain_ttl_secs
             .store(drain_ttl_secs, Ordering::Relaxed);
+        self.me_pool_drain_threshold
+            .store(pool_drain_threshold, Ordering::Relaxed);
         self.me_pool_force_close_secs
             .store(force_close_secs, Ordering::Relaxed);
         self.me_pool_min_fresh_ratio_permille
@@ -513,6 +556,14 @@ impl MePool {
             .store(secret_atomic_snapshot, Ordering::Relaxed);
         self.me_deterministic_writer_sort
             .store(deterministic_writer_sort, Ordering::Relaxed);
+        let previous_writer_pick_mode = self.writer_pick_mode();
+        self.me_writer_pick_mode
+            .store(writer_pick_mode.as_u8(), Ordering::Relaxed);
+        self.me_writer_pick_sample_size
+            .store(writer_pick_sample_size.clamp(2, 4), Ordering::Relaxed);
+        if previous_writer_pick_mode != writer_pick_mode {
+            self.stats.increment_me_writer_pick_mode_switch_total();
+        }
         self.me_single_endpoint_shadow_writers
             .store(single_endpoint_shadow_writers, Ordering::Relaxed);
         self.me_single_endpoint_outage_mode_enabled
@@ -564,6 +615,12 @@ impl MePool {
             .store(adaptive_floor_max_active_writers_global, Ordering::Relaxed);
         self.me_adaptive_floor_max_warm_writers_global
             .store(adaptive_floor_max_warm_writers_global, Ordering::Relaxed);
+        self.me_health_interval_ms_unhealthy
+            .store(me_health_interval_ms_unhealthy.max(1), Ordering::Relaxed);
+        self.me_health_interval_ms_healthy
+            .store(me_health_interval_ms_healthy.max(1), Ordering::Relaxed);
+        self.me_warn_rate_limit_ms
+            .store(me_warn_rate_limit_ms.max(1), Ordering::Relaxed);
         if previous_floor_mode != floor_mode {
             self.stats.increment_me_floor_mode_switch_total();
             match (previous_floor_mode, floor_mode) {
@@ -588,9 +645,9 @@ impl MePool {
         }
     }
 
+    /// Translate the local ME address into the address material sent to the proxy.
     pub fn translate_our_addr(&self, addr: SocketAddr) -> SocketAddr {
-        let ip = self.translate_ip_for_nat(addr.ip());
-        SocketAddr::new(ip, addr.port())
+        self.translate_our_addr_with_reflection(addr, None)
     }
 
     pub fn registry(&self) -> &Arc<ConnRegistry> {
@@ -603,9 +660,12 @@ impl MePool {
         route_backpressure_base_timeout_ms: u64,
         route_backpressure_high_timeout_ms: u64,
         route_backpressure_high_watermark_pct: u8,
+        reader_route_data_wait_ms: u64,
     ) {
         self.me_socks_kdf_policy
             .store(socks_kdf_policy.as_u8(), Ordering::Relaxed);
+        self.me_reader_route_data_wait_ms
+            .store(reader_route_data_wait_ms, Ordering::Relaxed);
         self.registry.update_route_backpressure_policy(
             route_backpressure_base_timeout_ms,
             route_backpressure_high_timeout_ms,
@@ -664,6 +724,16 @@ impl MePool {
         MeBindStaleMode::from_u8(self.me_bind_stale_mode.load(Ordering::Relaxed))
     }
 
+    pub(super) fn writer_pick_mode(&self) -> MeWriterPickMode {
+        MeWriterPickMode::from_u8(self.me_writer_pick_mode.load(Ordering::Relaxed))
+    }
+
+    pub(super) fn writer_pick_sample_size(&self) -> usize {
+        self.me_writer_pick_sample_size
+            .load(Ordering::Relaxed)
+            .clamp(2, 4) as usize
+    }
+
     pub(super) fn required_writers_for_dc(&self, endpoint_count: usize) -> usize {
         if endpoint_count == 0 {
             return 0;
@@ -765,10 +835,29 @@ impl MePool {
         effective
     }
 
+    // Keeps per-contour (active/warm) writer budget bounded by CPU count.
+    // Baseline is 86 writers on the first core and +48 for each extra core.
+    fn adaptive_floor_cpu_budget_per_contour_cap(&self, cores: usize) -> usize {
+        const FIRST_CORE_WRITER_BUDGET: usize = 86;
+        const EXTRA_CORE_WRITER_BUDGET: usize = 48;
+        if cores == 0 {
+            return FIRST_CORE_WRITER_BUDGET;
+        }
+        FIRST_CORE_WRITER_BUDGET.saturating_add(
+            cores
+                .saturating_sub(1)
+                .saturating_mul(EXTRA_CORE_WRITER_BUDGET),
+        )
+    }
+
     pub(super) fn adaptive_floor_active_cap_configured_total(&self) -> usize {
         let cores = self.adaptive_floor_effective_cpu_cores();
-        let per_core_cap = cores.saturating_mul(self.adaptive_floor_max_active_writers_per_core());
-        let configured = per_core_cap.min(self.adaptive_floor_max_active_writers_global());
+        let per_contour_budget = self.adaptive_floor_cpu_budget_per_contour_cap(cores);
+        let configured = cores
+            .saturating_mul(self.adaptive_floor_max_active_writers_per_core())
+            .min(self.adaptive_floor_max_active_writers_global())
+            .min(per_contour_budget)
+            .max(1);
         self.me_adaptive_floor_active_cap_configured
             .store(configured as u64, Ordering::Relaxed);
         self.stats
@@ -778,8 +867,12 @@ impl MePool {
 
     pub(super) fn adaptive_floor_warm_cap_configured_total(&self) -> usize {
         let cores = self.adaptive_floor_effective_cpu_cores();
-        let per_core_cap = cores.saturating_mul(self.adaptive_floor_max_warm_writers_per_core());
-        let configured = per_core_cap.min(self.adaptive_floor_max_warm_writers_global());
+        let per_contour_budget = self.adaptive_floor_cpu_budget_per_contour_cap(cores);
+        let configured = cores
+            .saturating_mul(self.adaptive_floor_max_warm_writers_per_core())
+            .min(self.adaptive_floor_max_warm_writers_global())
+            .min(per_contour_budget)
+            .max(1);
         self.me_adaptive_floor_warm_cap_configured
             .store(configured as u64, Ordering::Relaxed);
         self.stats
@@ -1042,6 +1135,62 @@ impl MePool {
         }
     }
 
+    fn build_preferred_endpoints_by_dc(
+        decision: &NetworkDecision,
+        map_v4: &HashMap<i32, Vec<(IpAddr, u16)>>,
+        map_v6: &HashMap<i32, Vec<(IpAddr, u16)>>,
+    ) -> HashMap<i32, Vec<SocketAddr>> {
+        let mut out = HashMap::<i32, Vec<SocketAddr>>::new();
+        let mut dcs = HashSet::<i32>::new();
+        dcs.extend(map_v4.keys().copied());
+        dcs.extend(map_v6.keys().copied());
+
+        for dc in dcs {
+            let v4 = map_v4
+                .get(&dc)
+                .map(|items| {
+                    items
+                        .iter()
+                        .map(|(ip, port)| SocketAddr::new(*ip, *port))
+                        .collect::<Vec<_>>()
+                })
+                .unwrap_or_default();
+            let v6 = map_v6
+                .get(&dc)
+                .map(|items| {
+                    items
+                        .iter()
+                        .map(|(ip, port)| SocketAddr::new(*ip, *port))
+                        .collect::<Vec<_>>()
+                })
+                .unwrap_or_default();
+
+            let mut selected = if decision.effective_multipath {
+                let mut both = Vec::<SocketAddr>::with_capacity(v4.len().saturating_add(v6.len()));
+                if decision.prefer_ipv6() {
+                    both.extend(v6.iter().copied());
+                    both.extend(v4.iter().copied());
+                } else {
+                    both.extend(v4.iter().copied());
+                    both.extend(v6.iter().copied());
+                }
+                both
+            } else if decision.prefer_ipv6() {
+                if !v6.is_empty() { v6 } else { v4 }
+            } else if !v4.is_empty() {
+                v4
+            } else {
+                v6
+            };
+
+            selected.sort_unstable();
+            selected.dedup();
+            out.insert(dc, selected);
+        }
+
+        out
+    }
+
     fn build_endpoint_dc_map_from_maps(
         map_v4: &HashMap<i32, Vec<(IpAddr, u16)>>,
         map_v6: &HashMap<i32, Vec<(IpAddr, u16)>>,
@@ -1064,6 +1213,25 @@ impl MePool {
         let map_v4 = self.proxy_map_v4.read().await.clone();
         let map_v6 = self.proxy_map_v6.read().await.clone();
         let rebuilt = Self::build_endpoint_dc_map_from_maps(&map_v4, &map_v6);
+        let preferred = Self::build_preferred_endpoints_by_dc(&self.decision, &map_v4, &map_v6);
         *self.endpoint_dc_map.write().await = rebuilt;
+        *self.preferred_endpoints_by_dc.write().await = preferred;
+    }
+
+    pub(super) async fn preferred_endpoints_for_dc(&self, dc: i32) -> Vec<SocketAddr> {
+        let guard = self.preferred_endpoints_by_dc.read().await;
+        guard.get(&dc).cloned().unwrap_or_default()
+    }
+
+    pub(super) fn health_interval_unhealthy(&self) -> Duration {
+        Duration::from_millis(self.me_health_interval_ms_unhealthy.load(Ordering::Relaxed).max(1))
+    }
+
+    pub(super) fn health_interval_healthy(&self) -> Duration {
+        Duration::from_millis(self.me_health_interval_ms_healthy.load(Ordering::Relaxed).max(1))
+    }
+
+    pub(super) fn warn_rate_limit_duration(&self) -> Duration {
+        Duration::from_millis(self.me_warn_rate_limit_ms.load(Ordering::Relaxed).max(1))
     }
 }

src/transport/middle_proxy/pool_nat.rs

@@ -159,7 +159,13 @@ impl MePool {
         addr: std::net::SocketAddr,
         reflected: Option<std::net::SocketAddr>,
     ) -> std::net::SocketAddr {
-        let ip = if let Some(r) = reflected {
+        let ip = if let Some(nat_ip) = self.nat_ip_cfg {
+            match (addr.ip(), nat_ip) {
+                (IpAddr::V4(_), IpAddr::V4(dst)) => IpAddr::V4(dst),
+                (IpAddr::V6(_), IpAddr::V6(dst)) => IpAddr::V6(dst),
+                _ => addr.ip(),
+            }
+        } else if let Some(r) = reflected {
             // Use reflected IP (not port) only when local address is non-public.
             if is_bogon(addr.ip()) || addr.ip().is_loopback() || addr.ip().is_unspecified() {
                 r.ip()

src/transport/middle_proxy/pool_refill.rs

@@ -1,4 +1,4 @@
-use std::collections::HashSet;
+use std::collections::{HashMap, HashSet};
 use std::net::SocketAddr;
 use std::sync::Arc;
 use std::sync::atomic::Ordering;
@@ -113,10 +113,35 @@ impl MePool {
         contour: WriterContour,
         allow_coverage_override: bool,
     ) -> bool {
-        let candidates = self.connectable_endpoints(endpoints).await;
+        let mut candidates = self.connectable_endpoints(endpoints).await;
         if candidates.is_empty() {
             return false;
         }
+        if candidates.len() > 1 {
+            let mut active_by_endpoint = HashMap::<SocketAddr, usize>::new();
+            let ws = self.writers.read().await;
+            for writer in ws.iter() {
+                if writer.draining.load(Ordering::Relaxed) {
+                    continue;
+                }
+                if writer.writer_dc != dc {
+                    continue;
+                }
+                if !matches!(
+                    super::pool::WriterContour::from_u8(
+                        writer.contour.load(Ordering::Relaxed),
+                    ),
+                    super::pool::WriterContour::Active
+                ) {
+                    continue;
+                }
+                if candidates.contains(&writer.addr) {
+                    *active_by_endpoint.entry(writer.addr).or_insert(0) += 1;
+                }
+            }
+            drop(ws);
+            candidates.sort_by_key(|addr| (active_by_endpoint.get(addr).copied().unwrap_or(0), *addr));
+        }
         let start = (self.rr.fetch_add(1, Ordering::Relaxed) as usize) % candidates.len();
         for offset in 0..candidates.len() {
             let idx = (start + offset) % candidates.len();

src/transport/middle_proxy/pool_status.rs

@@ -19,12 +19,19 @@ pub(crate) struct MeApiWriterStatusSnapshot {
     pub bound_clients: usize,
     pub idle_for_secs: Option<u64>,
     pub rtt_ema_ms: Option<f64>,
+    pub matches_active_generation: bool,
+    pub in_desired_map: bool,
+    pub allow_drain_fallback: bool,
+    pub drain_started_at_epoch_secs: Option<u64>,
+    pub drain_deadline_epoch_secs: Option<u64>,
+    pub drain_over_ttl: bool,
 }
 
 #[derive(Clone, Debug)]
 pub(crate) struct MeApiDcStatusSnapshot {
     pub dc: i16,
     pub endpoints: Vec<SocketAddr>,
+    pub endpoint_writers: Vec<MeApiDcEndpointWriterSnapshot>,
     pub available_endpoints: usize,
     pub available_pct: f64,
     pub required_writers: usize,
@@ -34,10 +41,18 @@ pub(crate) struct MeApiDcStatusSnapshot {
     pub floor_capped: bool,
     pub alive_writers: usize,
     pub coverage_pct: f64,
+    pub fresh_alive_writers: usize,
+    pub fresh_coverage_pct: f64,
     pub rtt_ms: Option<f64>,
     pub load: usize,
 }
 
+#[derive(Clone, Debug)]
+pub(crate) struct MeApiDcEndpointWriterSnapshot {
+    pub endpoint: SocketAddr,
+    pub active_writers: usize,
+}
+
 #[derive(Clone, Debug)]
 pub(crate) struct MeApiStatusSnapshot {
     pub generated_at_epoch_secs: u64,
@@ -48,6 +63,8 @@ pub(crate) struct MeApiStatusSnapshot {
     pub required_writers: usize,
     pub alive_writers: usize,
     pub coverage_pct: f64,
+    pub fresh_alive_writers: usize,
+    pub fresh_coverage_pct: f64,
     pub writers: Vec<MeApiWriterStatusSnapshot>,
     pub dcs: Vec<MeApiDcStatusSnapshot>,
 }
@@ -118,6 +135,8 @@ pub(crate) struct MeApiRuntimeSnapshot {
     pub me_single_endpoint_outage_backoff_max_ms: u64,
     pub me_single_endpoint_shadow_rotate_every_secs: u64,
     pub me_deterministic_writer_sort: bool,
+    pub me_writer_pick_mode: &'static str,
+    pub me_writer_pick_sample_size: u8,
     pub me_socks_kdf_policy: &'static str,
     pub quarantined_endpoints: Vec<MeApiQuarantinedEndpointSnapshot>,
     pub network_path: Vec<MeApiDcPathSnapshot>,
@@ -204,6 +223,8 @@ impl MePool {
 
     pub(crate) async fn api_status_snapshot(&self) -> MeApiStatusSnapshot {
         let now_epoch_secs = Self::now_epoch_secs();
+        let active_generation = self.current_generation();
+        let drain_ttl_secs = self.me_pool_drain_ttl_secs.load(Ordering::Relaxed);
 
         let mut endpoints_by_dc = BTreeMap::<i16, BTreeSet<SocketAddr>>::new();
         if self.decision.ipv4_me {
@@ -230,6 +251,7 @@ impl MePool {
 
         let mut live_writers_by_dc_endpoint = HashMap::<(i16, SocketAddr), usize>::new();
         let mut live_writers_by_dc = HashMap::<i16, usize>::new();
+        let mut fresh_writers_by_dc = HashMap::<i16, usize>::new();
         let mut dc_rtt_agg = HashMap::<i16, (f64, u64)>::new();
         let mut writer_rows = Vec::<MeApiWriterStatusSnapshot>::with_capacity(writers.len());
 
@@ -238,6 +260,10 @@ impl MePool {
             let dc = i16::try_from(writer.writer_dc).ok();
             let draining = writer.draining.load(Ordering::Relaxed);
             let degraded = writer.degraded.load(Ordering::Relaxed);
+            let matches_active_generation = writer.generation == active_generation;
+            let in_desired_map = dc
+                .and_then(|dc_idx| endpoints_by_dc.get(&dc_idx))
+                .is_some_and(|endpoints| endpoints.contains(&endpoint));
             let bound_clients = activity
                 .bound_clients_by_writer
                 .get(&writer.id)
@@ -247,6 +273,21 @@ impl MePool {
                 .get(&writer.id)
                 .map(|idle_ts| now_epoch_secs.saturating_sub(*idle_ts));
             let rtt_ema_ms = rtt.get(&writer.id).map(|(_, ema)| *ema);
+            let allow_drain_fallback = writer.allow_drain_fallback.load(Ordering::Relaxed);
+            let drain_started_at_epoch_secs = writer
+                .draining_started_at_epoch_secs
+                .load(Ordering::Relaxed);
+            let drain_deadline_epoch_secs = writer
+                .drain_deadline_epoch_secs
+                .load(Ordering::Relaxed);
+            let drain_started_at_epoch_secs =
+                (drain_started_at_epoch_secs != 0).then_some(drain_started_at_epoch_secs);
+            let drain_deadline_epoch_secs =
+                (drain_deadline_epoch_secs != 0).then_some(drain_deadline_epoch_secs);
+            let drain_over_ttl = draining
+                && drain_ttl_secs > 0
+                && drain_started_at_epoch_secs
+                    .is_some_and(|started| now_epoch_secs.saturating_sub(started) > drain_ttl_secs);
             let state = match WriterContour::from_u8(writer.contour.load(Ordering::Relaxed)) {
                 WriterContour::Warm => "warm",
                 WriterContour::Active => "active",
@@ -264,6 +305,9 @@ impl MePool {
                         entry.0 += ema_ms;
                         entry.1 += 1;
                     }
+                    if matches_active_generation && in_desired_map {
+                        *fresh_writers_by_dc.entry(dc_idx).or_insert(0) += 1;
+                    }
                 }
             }
 
@@ -278,6 +322,12 @@ impl MePool {
                 bound_clients,
                 idle_for_secs,
                 rtt_ema_ms,
+                matches_active_generation,
+                in_desired_map,
+                allow_drain_fallback,
+                drain_started_at_epoch_secs,
+                drain_deadline_epoch_secs,
+                drain_over_ttl,
             });
         }
 
@@ -286,6 +336,7 @@ impl MePool {
         let mut dcs = Vec::<MeApiDcStatusSnapshot>::with_capacity(endpoints_by_dc.len());
         let mut available_endpoints = 0usize;
         let mut alive_writers = 0usize;
+        let mut fresh_alive_writers = 0usize;
         let floor_mode = self.floor_mode();
         let adaptive_cpu_cores = (self
             .me_adaptive_floor_cpu_cores_effective
@@ -324,6 +375,7 @@ impl MePool {
             let floor_capped = matches!(floor_mode, MeFloorMode::Adaptive)
                 && dc_required_writers < base_required;
             let dc_alive_writers = live_writers_by_dc.get(&dc).copied().unwrap_or(0);
+            let dc_fresh_alive_writers = fresh_writers_by_dc.get(&dc).copied().unwrap_or(0);
             let dc_load = activity
                 .active_sessions_by_target_dc
                 .get(&dc)
@@ -335,9 +387,20 @@ impl MePool {
 
             available_endpoints += dc_available_endpoints;
             alive_writers += dc_alive_writers;
+            fresh_alive_writers += dc_fresh_alive_writers;
 
             dcs.push(MeApiDcStatusSnapshot {
                 dc,
+                endpoint_writers: endpoints
+                    .iter()
+                    .map(|endpoint| MeApiDcEndpointWriterSnapshot {
+                        endpoint: *endpoint,
+                        active_writers: live_writers_by_dc_endpoint
+                            .get(&(dc, *endpoint))
+                            .copied()
+                            .unwrap_or(0),
+                    })
+                    .collect(),
                 endpoints: endpoints.into_iter().collect(),
                 available_endpoints: dc_available_endpoints,
                 available_pct: ratio_pct(dc_available_endpoints, endpoint_count),
@@ -348,6 +411,8 @@ impl MePool {
                 floor_capped,
                 alive_writers: dc_alive_writers,
                 coverage_pct: ratio_pct(dc_alive_writers, dc_required_writers),
+                fresh_alive_writers: dc_fresh_alive_writers,
+                fresh_coverage_pct: ratio_pct(dc_fresh_alive_writers, dc_required_writers),
                 rtt_ms: dc_rtt_ms,
                 load: dc_load,
             });
@@ -362,6 +427,8 @@ impl MePool {
             required_writers,
             alive_writers,
             coverage_pct: ratio_pct(alive_writers, required_writers),
+            fresh_alive_writers,
+            fresh_coverage_pct: ratio_pct(fresh_alive_writers, required_writers),
             writers: writer_rows,
             dcs,
         }
@@ -522,6 +589,8 @@ impl MePool {
             me_deterministic_writer_sort: self
                 .me_deterministic_writer_sort
                 .load(Ordering::Relaxed),
+            me_writer_pick_mode: writer_pick_mode_label(self.writer_pick_mode()),
+            me_writer_pick_sample_size: self.writer_pick_sample_size() as u8,
             me_socks_kdf_policy: socks_kdf_policy_label(self.socks_kdf_policy()),
             quarantined_endpoints,
             network_path,
@@ -570,6 +639,13 @@ fn bind_stale_mode_label(mode: MeBindStaleMode) -> &'static str {
     }
 }
 
+fn writer_pick_mode_label(mode: crate::config::MeWriterPickMode) -> &'static str {
+    match mode {
+        crate::config::MeWriterPickMode::SortedRr => "sorted_rr",
+        crate::config::MeWriterPickMode::P2c => "p2c",
+    }
+}
+
 fn socks_kdf_policy_label(policy: MeSocksKdfPolicy) -> &'static str {
     match policy {
         MeSocksKdfPolicy::Strict => "strict",

src/transport/middle_proxy/pool_writer.rs

@@ -1,6 +1,6 @@
 use std::net::SocketAddr;
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU64, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU32, AtomicU64, Ordering};
 use std::time::{Duration, Instant};
 use std::io::ErrorKind;
 
@@ -128,11 +128,12 @@ impl MePool {
         let contour = Arc::new(AtomicU8::new(contour.as_u8()));
         let cancel = CancellationToken::new();
         let degraded = Arc::new(AtomicBool::new(false));
+        let rtt_ema_ms_x10 = Arc::new(AtomicU32::new(0));
         let draining = Arc::new(AtomicBool::new(false));
         let draining_started_at_epoch_secs = Arc::new(AtomicU64::new(0));
         let drain_deadline_epoch_secs = Arc::new(AtomicU64::new(0));
         let allow_drain_fallback = Arc::new(AtomicBool::new(false));
-        let (tx, mut rx) = mpsc::channel::<WriterCommand>(4096);
+        let (tx, mut rx) = mpsc::channel::<WriterCommand>(self.writer_cmd_channel_capacity);
         let mut rpc_writer = RpcWriter {
             writer: hs.wr,
             key: hs.write_key,
@@ -162,6 +163,7 @@ impl MePool {
         let writer = MeWriter {
             id: writer_id,
             addr,
+            source_ip: hs.source_ip,
             writer_dc,
             generation,
             contour: contour.clone(),
@@ -169,12 +171,14 @@ impl MePool {
             tx: tx.clone(),
             cancel: cancel.clone(),
             degraded: degraded.clone(),
+            rtt_ema_ms_x10: rtt_ema_ms_x10.clone(),
             draining: draining.clone(),
             draining_started_at_epoch_secs: draining_started_at_epoch_secs.clone(),
             drain_deadline_epoch_secs: drain_deadline_epoch_secs.clone(),
             allow_drain_fallback: allow_drain_fallback.clone(),
         };
         self.writers.write().await.push(writer.clone());
+        self.registry.register_writer(writer_id, tx.clone()).await;
         self.registry.mark_writer_idle(writer_id).await;
         self.conn_count.fetch_add(1, Ordering::Relaxed);
         self.writer_available.notify_one();
@@ -206,6 +210,7 @@ impl MePool {
         let keepalive_jitter_signal = self.me_keepalive_jitter;
         let cancel_reader_token = cancel.clone();
         let cancel_ping_token = cancel_ping.clone();
+        let reader_route_data_wait_ms = self.me_reader_route_data_wait_ms.clone();
 
         tokio::spawn(async move {
             let res = reader_loop(
@@ -222,6 +227,8 @@ impl MePool {
                 stats_reader,
                 writer_id,
                 degraded.clone(),
+                rtt_ema_ms_x10.clone(),
+                reader_route_data_wait_ms,
                 cancel_reader_token.clone(),
             )
             .await;
@@ -408,9 +415,15 @@ impl MePool {
                 };
 
                 let (conn_id, mut service_rx) = pool.registry.register().await;
-                pool.registry
-                    .bind_writer(conn_id, writer_id, tx_signal.clone(), meta.clone())
-                    .await;
+                if !pool
+                    .registry
+                    .bind_writer(conn_id, writer_id, meta.clone())
+                    .await
+                {
+                    let _ = pool.registry.unregister(conn_id).await;
+                    stats_signal.increment_me_rpc_proxy_req_signal_skipped_no_meta_total();
+                    continue;
+                }
 
                 let payload = build_proxy_req_payload(
                     conn_id,
@@ -515,6 +528,12 @@ impl MePool {
                 self.conn_count.fetch_sub(1, Ordering::Relaxed);
             }
         }
+        let conns = self.registry.writer_lost(writer_id).await;
+        {
+            let mut tracker = self.ping_tracker.lock().await;
+            tracker.retain(|_, (_, wid)| *wid != writer_id);
+        }
+        self.rtt_stats.lock().await.remove(&writer_id);
         if let Some(tx) = close_tx {
             let _ = tx.send(WriterCommand::Close).await;
         }
@@ -527,8 +546,7 @@ impl MePool {
             }
             self.trigger_immediate_refill_for_dc(addr, writer_dc);
         }
-        self.rtt_stats.lock().await.remove(&writer_id);
-        self.registry.writer_lost(writer_id).await
+        conns
     }
 
     pub(crate) async fn mark_writer_draining_with_timeout(

src/transport/middle_proxy/reader.rs

@@ -1,7 +1,7 @@
 use std::collections::HashMap;
 use std::io::ErrorKind;
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, Ordering};
 use std::time::Instant;
 
 use bytes::{Bytes, BytesMut};
@@ -34,6 +34,8 @@ pub(crate) async fn reader_loop(
     stats: Arc<Stats>,
     _writer_id: u64,
     degraded: Arc<AtomicBool>,
+    writer_rtt_ema_ms_x10: Arc<AtomicU32>,
+    reader_route_data_wait_ms: Arc<AtomicU64>,
     cancel: CancellationToken,
 ) -> Result<()> {
     let mut raw = enc_leftover;
@@ -56,17 +58,14 @@ pub(crate) async fn reader_loop(
 
         let blocks = raw.len() / 16 * 16;
         if blocks > 0 {
+            let mut chunk = raw.split_to(blocks);
             let mut new_iv = [0u8; 16];
-            new_iv.copy_from_slice(&raw[blocks - 16..blocks]);
-
-            let mut chunk = vec![0u8; blocks];
-            chunk.copy_from_slice(&raw[..blocks]);
+            new_iv.copy_from_slice(&chunk[blocks - 16..blocks]);
             AesCbc::new(dk, div)
-                .decrypt_in_place(&mut chunk)
+                .decrypt_in_place(&mut chunk[..])
                 .map_err(|e| ProxyError::Crypto(format!("{e}")))?;
             div = new_iv;
             dec.extend_from_slice(&chunk);
-            let _ = raw.split_to(blocks);
         }
 
         while dec.len() >= 12 {
@@ -84,7 +83,7 @@ pub(crate) async fn reader_loop(
                 break;
             }
 
-            let frame = dec.split_to(fl);
+            let frame = dec.split_to(fl).freeze();
             let pe = fl - 4;
             let ec = u32::from_le_bytes(frame[pe..pe + 4].try_into().unwrap());
             let actual_crc = rpc_crc(crc_mode, &frame[..pe]);
@@ -110,21 +109,27 @@ pub(crate) async fn reader_loop(
             }
             expected_seq = expected_seq.wrapping_add(1);
 
-            let payload = &frame[8..pe];
+            let payload = frame.slice(8..pe);
             if payload.len() < 4 {
                 continue;
             }
 
             let pt = u32::from_le_bytes(payload[0..4].try_into().unwrap());
-            let body = &payload[4..];
+            let body = payload.slice(4..);
 
             if pt == RPC_PROXY_ANS_U32 && body.len() >= 12 {
                 let flags = u32::from_le_bytes(body[0..4].try_into().unwrap());
                 let cid = u64::from_le_bytes(body[4..12].try_into().unwrap());
-                let data = Bytes::copy_from_slice(&body[12..]);
+                let data = body.slice(12..);
                 trace!(cid, flags, len = data.len(), "RPC_PROXY_ANS");
 
-                let routed = reg.route_nowait(cid, MeResponse::Data { flags, data }).await;
+                let data_wait_ms = reader_route_data_wait_ms.load(Ordering::Relaxed);
+                let routed = if data_wait_ms == 0 {
+                    reg.route_nowait(cid, MeResponse::Data { flags, data }).await
+                } else {
+                    reg.route_with_timeout(cid, MeResponse::Data { flags, data }, data_wait_ms)
+                        .await
+                };
                 if !matches!(routed, RouteResult::Routed) {
                     match routed {
                         RouteResult::NoConn => stats.increment_me_route_drop_no_conn(),
@@ -208,6 +213,8 @@ pub(crate) async fn reader_loop(
                     }
                     let degraded_now = entry.1 > entry.0 * 2.0;
                     degraded.store(degraded_now, Ordering::Relaxed);
+                    writer_rtt_ema_ms_x10
+                        .store((entry.1 * 10.0).clamp(0.0, u32::MAX as f64) as u32, Ordering::Relaxed);
                     trace!(writer_id = wid, rtt_ms = rtt, ema_ms = entry.1, base_ms = entry.0, degraded = degraded_now, "ME RTT sample");
                 }
             } else {

src/transport/middle_proxy/registry.rs

@@ -9,7 +9,6 @@ use tokio::sync::mpsc::error::TrySendError;
 use super::codec::WriterCommand;
 use super::MeResponse;
 
-const ROUTE_CHANNEL_CAPACITY: usize = 4096;
 const ROUTE_BACKPRESSURE_BASE_TIMEOUT_MS: u64 = 25;
 const ROUTE_BACKPRESSURE_HIGH_TIMEOUT_MS: u64 = 120;
 const ROUTE_BACKPRESSURE_HIGH_WATERMARK_PCT: u8 = 80;
@@ -78,6 +77,7 @@ impl RegistryInner {
 pub struct ConnRegistry {
     inner: RwLock<RegistryInner>,
     next_id: AtomicU64,
+    route_channel_capacity: usize,
     route_backpressure_base_timeout_ms: AtomicU64,
     route_backpressure_high_timeout_ms: AtomicU64,
     route_backpressure_high_watermark_pct: AtomicU8,
@@ -91,11 +91,12 @@ impl ConnRegistry {
             .as_secs()
     }
 
-    pub fn new() -> Self {
+    pub fn with_route_channel_capacity(route_channel_capacity: usize) -> Self {
         let start = rand::random::<u64>() | 1;
         Self {
             inner: RwLock::new(RegistryInner::new()),
             next_id: AtomicU64::new(start),
+            route_channel_capacity: route_channel_capacity.max(1),
             route_backpressure_base_timeout_ms: AtomicU64::new(
                 ROUTE_BACKPRESSURE_BASE_TIMEOUT_MS,
             ),
@@ -108,6 +109,11 @@ impl ConnRegistry {
         }
     }
 
+    #[cfg(test)]
+    pub fn new() -> Self {
+        Self::with_route_channel_capacity(4096)
+    }
+
     pub fn update_route_backpressure_policy(
         &self,
         base_timeout_ms: u64,
@@ -127,11 +133,20 @@ impl ConnRegistry {
 
     pub async fn register(&self) -> (u64, mpsc::Receiver<MeResponse>) {
         let id = self.next_id.fetch_add(1, Ordering::Relaxed);
-        let (tx, rx) = mpsc::channel(ROUTE_CHANNEL_CAPACITY);
+        let (tx, rx) = mpsc::channel(self.route_channel_capacity);
         self.inner.write().await.map.insert(id, tx);
         (id, rx)
     }
 
+    pub async fn register_writer(&self, writer_id: u64, tx: mpsc::Sender<WriterCommand>) {
+        let mut inner = self.inner.write().await;
+        inner.writers.insert(writer_id, tx);
+        inner
+            .conns_for_writer
+            .entry(writer_id)
+            .or_insert_with(HashSet::new);
+    }
+
     /// Unregister connection, returning associated writer_id if any.
     pub async fn unregister(&self, id: u64) -> Option<u64> {
         let mut inner = self.inner.write().await;
@@ -179,11 +194,11 @@ impl ConnRegistry {
                     .route_backpressure_high_watermark_pct
                     .load(Ordering::Relaxed)
                     .clamp(1, 100);
-                let used = ROUTE_CHANNEL_CAPACITY.saturating_sub(tx.capacity());
-                let used_pct = if ROUTE_CHANNEL_CAPACITY == 0 {
+                let used = self.route_channel_capacity.saturating_sub(tx.capacity());
+                let used_pct = if self.route_channel_capacity == 0 {
                     100
                 } else {
-                    (used.saturating_mul(100) / ROUTE_CHANNEL_CAPACITY) as u8
+                    (used.saturating_mul(100) / self.route_channel_capacity) as u8
                 };
                 let high_profile = used_pct >= high_watermark_pct;
                 let timeout_ms = if high_profile {
@@ -225,24 +240,90 @@ impl ConnRegistry {
         }
     }
 
-    pub async fn bind_writer(
+    pub async fn route_with_timeout(
         &self,
-        conn_id: u64,
-        writer_id: u64,
-        tx: mpsc::Sender<WriterCommand>,
-        meta: ConnMeta,
-    ) {
+        id: u64,
+        resp: MeResponse,
+        timeout_ms: u64,
+    ) -> RouteResult {
+        if timeout_ms == 0 {
+            return self.route_nowait(id, resp).await;
+        }
+
+        let tx = {
+            let inner = self.inner.read().await;
+            inner.map.get(&id).cloned()
+        };
+
+        let Some(tx) = tx else {
+            return RouteResult::NoConn;
+        };
+
+        match tx.try_send(resp) {
+            Ok(()) => RouteResult::Routed,
+            Err(TrySendError::Closed(_)) => RouteResult::ChannelClosed,
+            Err(TrySendError::Full(resp)) => {
+                let high_watermark_pct = self
+                    .route_backpressure_high_watermark_pct
+                    .load(Ordering::Relaxed)
+                    .clamp(1, 100);
+                let used = self.route_channel_capacity.saturating_sub(tx.capacity());
+                let used_pct = if self.route_channel_capacity == 0 {
+                    100
+                } else {
+                    (used.saturating_mul(100) / self.route_channel_capacity) as u8
+                };
+                let high_profile = used_pct >= high_watermark_pct;
+                let timeout_dur = Duration::from_millis(timeout_ms.max(1));
+
+                match tokio::time::timeout(timeout_dur, tx.send(resp)).await {
+                    Ok(Ok(())) => RouteResult::Routed,
+                    Ok(Err(_)) => RouteResult::ChannelClosed,
+                    Err(_) => {
+                        if high_profile {
+                            RouteResult::QueueFullHigh
+                        } else {
+                            RouteResult::QueueFullBase
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    pub async fn bind_writer(&self, conn_id: u64, writer_id: u64, meta: ConnMeta) -> bool {
         let mut inner = self.inner.write().await;
-        inner.meta.entry(conn_id).or_insert(meta.clone());
-        inner.writer_for_conn.insert(conn_id, writer_id);
+        if !inner.writers.contains_key(&writer_id) {
+            return false;
+        }
+
+        let previous_writer_id = inner.writer_for_conn.insert(conn_id, writer_id);
+        if let Some(previous_writer_id) = previous_writer_id
+            && previous_writer_id != writer_id
+        {
+            let became_empty = if let Some(set) = inner.conns_for_writer.get_mut(&previous_writer_id)
+            {
+                set.remove(&conn_id);
+                set.is_empty()
+            } else {
+                false
+            };
+            if became_empty {
+                inner
+                    .writer_idle_since_epoch_secs
+                    .insert(previous_writer_id, Self::now_epoch_secs());
+            }
+        }
+
+        inner.meta.insert(conn_id, meta.clone());
         inner.last_meta_for_writer.insert(writer_id, meta);
         inner.writer_idle_since_epoch_secs.remove(&writer_id);
-        inner.writers.entry(writer_id).or_insert_with(|| tx.clone());
         inner
             .conns_for_writer
             .entry(writer_id)
             .or_insert_with(HashSet::new)
             .insert(conn_id);
+        true
     }
 
     pub async fn mark_writer_idle(&self, writer_id: u64) {
@@ -327,6 +408,9 @@ impl ConnRegistry {
 
         let mut out = Vec::new();
         for conn_id in conns {
+            if inner.writer_for_conn.get(&conn_id).copied() != Some(writer_id) {
+                continue;
+            }
             inner.writer_for_conn.remove(&conn_id);
             if let Some(m) = inner.meta.get(&conn_id) {
                 out.push(BoundConn {
@@ -370,47 +454,52 @@ mod tests {
         let (conn_c, _rx_c) = registry.register().await;
         let (writer_tx_a, _writer_rx_a) = tokio::sync::mpsc::channel(8);
         let (writer_tx_b, _writer_rx_b) = tokio::sync::mpsc::channel(8);
+        registry.register_writer(10, writer_tx_a.clone()).await;
+        registry.register_writer(20, writer_tx_b.clone()).await;
 
         let addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 443);
-        registry
-            .bind_writer(
-                conn_a,
-                10,
-                writer_tx_a.clone(),
-                ConnMeta {
-                    target_dc: 2,
-                    client_addr: addr,
-                    our_addr: addr,
-                    proto_flags: 0,
-                },
-            )
-            .await;
-        registry
-            .bind_writer(
-                conn_b,
-                10,
-                writer_tx_a,
-                ConnMeta {
-                    target_dc: -2,
-                    client_addr: addr,
-                    our_addr: addr,
-                    proto_flags: 0,
-                },
-            )
-            .await;
-        registry
-            .bind_writer(
-                conn_c,
-                20,
-                writer_tx_b,
-                ConnMeta {
-                    target_dc: 4,
-                    client_addr: addr,
-                    our_addr: addr,
-                    proto_flags: 0,
-                },
-            )
-            .await;
+        assert!(
+            registry
+                .bind_writer(
+                    conn_a,
+                    10,
+                    ConnMeta {
+                        target_dc: 2,
+                        client_addr: addr,
+                        our_addr: addr,
+                        proto_flags: 0,
+                    },
+                )
+                .await
+        );
+        assert!(
+            registry
+                .bind_writer(
+                    conn_b,
+                    10,
+                    ConnMeta {
+                        target_dc: -2,
+                        client_addr: addr,
+                        our_addr: addr,
+                        proto_flags: 0,
+                    },
+                )
+                .await
+        );
+        assert!(
+            registry
+                .bind_writer(
+                    conn_c,
+                    20,
+                    ConnMeta {
+                        target_dc: 4,
+                        client_addr: addr,
+                        our_addr: addr,
+                        proto_flags: 0,
+                    },
+                )
+                .await
+        );
 
         let snapshot = registry.writer_activity_snapshot().await;
         assert_eq!(snapshot.bound_clients_by_writer.get(&10), Some(&2));
@@ -419,4 +508,130 @@ mod tests {
         assert_eq!(snapshot.active_sessions_by_target_dc.get(&-2), Some(&1));
         assert_eq!(snapshot.active_sessions_by_target_dc.get(&4), Some(&1));
     }
+
+    #[tokio::test]
+    async fn bind_writer_rebinds_conn_atomically() {
+        let registry = ConnRegistry::new();
+        let (conn_id, _rx) = registry.register().await;
+        let (writer_tx_a, _writer_rx_a) = tokio::sync::mpsc::channel(8);
+        let (writer_tx_b, _writer_rx_b) = tokio::sync::mpsc::channel(8);
+        registry.register_writer(10, writer_tx_a).await;
+        registry.register_writer(20, writer_tx_b).await;
+
+        let client_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 443);
+        let first_our_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(1, 1, 1, 1)), 443);
+        let second_our_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(2, 2, 2, 2)), 443);
+
+        assert!(
+            registry
+                .bind_writer(
+                    conn_id,
+                    10,
+                    ConnMeta {
+                        target_dc: 2,
+                        client_addr,
+                        our_addr: first_our_addr,
+                        proto_flags: 1,
+                    },
+                )
+                .await
+        );
+        assert!(
+            registry
+                .bind_writer(
+                    conn_id,
+                    20,
+                    ConnMeta {
+                        target_dc: 2,
+                        client_addr,
+                        our_addr: second_our_addr,
+                        proto_flags: 2,
+                    },
+                )
+                .await
+        );
+
+        let writer = registry.get_writer(conn_id).await.expect("writer binding");
+        assert_eq!(writer.writer_id, 20);
+
+        let meta = registry.get_meta(conn_id).await.expect("conn meta");
+        assert_eq!(meta.our_addr, second_our_addr);
+        assert_eq!(meta.proto_flags, 2);
+
+        let snapshot = registry.writer_activity_snapshot().await;
+        assert_eq!(snapshot.bound_clients_by_writer.get(&10), Some(&0));
+        assert_eq!(snapshot.bound_clients_by_writer.get(&20), Some(&1));
+        assert!(registry.writer_idle_since_snapshot().await.contains_key(&10));
+    }
+
+    #[tokio::test]
+    async fn writer_lost_does_not_drop_rebound_conn() {
+        let registry = ConnRegistry::new();
+        let (conn_id, _rx) = registry.register().await;
+        let (writer_tx_a, _writer_rx_a) = tokio::sync::mpsc::channel(8);
+        let (writer_tx_b, _writer_rx_b) = tokio::sync::mpsc::channel(8);
+        registry.register_writer(10, writer_tx_a).await;
+        registry.register_writer(20, writer_tx_b).await;
+
+        let addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 443);
+        assert!(
+            registry
+                .bind_writer(
+                    conn_id,
+                    10,
+                    ConnMeta {
+                        target_dc: 2,
+                        client_addr: addr,
+                        our_addr: addr,
+                        proto_flags: 0,
+                    },
+                )
+                .await
+        );
+        assert!(
+            registry
+                .bind_writer(
+                    conn_id,
+                    20,
+                    ConnMeta {
+                        target_dc: 2,
+                        client_addr: addr,
+                        our_addr: addr,
+                        proto_flags: 1,
+                    },
+                )
+                .await
+        );
+
+        let lost = registry.writer_lost(10).await;
+        assert!(lost.is_empty());
+        assert_eq!(registry.get_writer(conn_id).await.expect("writer").writer_id, 20);
+
+        let removed_writer = registry.unregister(conn_id).await;
+        assert_eq!(removed_writer, Some(20));
+        assert!(registry.is_writer_empty(20).await);
+    }
+
+    #[tokio::test]
+    async fn bind_writer_rejects_unregistered_writer() {
+        let registry = ConnRegistry::new();
+        let (conn_id, _rx) = registry.register().await;
+        let addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 443);
+
+        assert!(
+            !registry
+                .bind_writer(
+                    conn_id,
+                    10,
+                    ConnMeta {
+                        target_dc: 2,
+                        client_addr: addr,
+                        our_addr: addr,
+                        proto_flags: 0,
+                    },
+                )
+                .await
+        );
+        assert!(registry.get_writer(conn_id).await.is_none());
+    }
 }

src/transport/middle_proxy/secret.rs

@@ -3,6 +3,7 @@ use std::time::SystemTime;
 use httpdate;
 
 use crate::error::{ProxyError, Result};
+use super::selftest::record_timeskew_sample;
 
 pub const PROXY_SECRET_MIN_LEN: usize = 32;
 
@@ -98,6 +99,7 @@ pub async fn download_proxy_secret_with_max_len(max_len: usize) -> Result<Vec<u8
         })
     {
         let skew_secs = skew.as_secs();
+        record_timeskew_sample("proxy_secret_date_header", skew_secs);
         if skew_secs > 60 {
             warn!(skew_secs, "Time skew >60s detected from proxy-secret Date header");
         } else if skew_secs > 30 {

src/transport/middle_proxy/selftest.rs

@@ -0,0 +1,260 @@
+use std::collections::{HashMap, VecDeque};
+use std::net::{IpAddr, SocketAddr};
+use std::sync::{Mutex, OnceLock};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum BndAddrStatus {
+    Ok,
+    Bogon,
+    Error,
+}
+
+impl BndAddrStatus {
+    pub(crate) fn as_str(self) -> &'static str {
+        match self {
+            Self::Ok => "ok",
+            Self::Bogon => "bogon",
+            Self::Error => "error",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum BndPortStatus {
+    Ok,
+    Zero,
+    Error,
+}
+
+impl BndPortStatus {
+    pub(crate) fn as_str(self) -> &'static str {
+        match self {
+            Self::Ok => "ok",
+            Self::Zero => "zero",
+            Self::Error => "error",
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeBndSnapshot {
+    pub addr_status: &'static str,
+    pub port_status: &'static str,
+    pub last_addr: Option<SocketAddr>,
+    pub last_seen_age_secs: Option<u64>,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeUpstreamBndSnapshot {
+    pub upstream_id: usize,
+    pub addr_status: &'static str,
+    pub port_status: &'static str,
+    pub last_addr: Option<SocketAddr>,
+    pub last_ip: Option<IpAddr>,
+    pub last_seen_age_secs: Option<u64>,
+}
+
+#[derive(Clone, Debug, Default)]
+pub(crate) struct MeTimeskewSnapshot {
+    pub max_skew_secs_15m: Option<u64>,
+    pub samples_15m: usize,
+    pub last_skew_secs: Option<u64>,
+    pub last_source: Option<&'static str>,
+    pub last_seen_age_secs: Option<u64>,
+}
+
+#[derive(Clone, Copy, Debug)]
+struct MeTimeskewSample {
+    ts_epoch_secs: u64,
+    skew_secs: u64,
+    source: &'static str,
+}
+
+#[derive(Debug)]
+struct MeSelftestState {
+    bnd_addr_status: BndAddrStatus,
+    bnd_port_status: BndPortStatus,
+    bnd_last_addr: Option<SocketAddr>,
+    bnd_last_seen_epoch_secs: Option<u64>,
+    upstream_bnd: HashMap<usize, UpstreamBndState>,
+    timeskew_samples: VecDeque<MeTimeskewSample>,
+}
+
+#[derive(Clone, Copy, Debug)]
+struct UpstreamBndState {
+    addr_status: BndAddrStatus,
+    port_status: BndPortStatus,
+    last_addr: Option<SocketAddr>,
+    last_ip: Option<IpAddr>,
+    last_seen_epoch_secs: Option<u64>,
+}
+
+impl Default for MeSelftestState {
+    fn default() -> Self {
+        Self {
+            bnd_addr_status: BndAddrStatus::Error,
+            bnd_port_status: BndPortStatus::Error,
+            bnd_last_addr: None,
+            bnd_last_seen_epoch_secs: None,
+            upstream_bnd: HashMap::new(),
+            timeskew_samples: VecDeque::new(),
+        }
+    }
+}
+
+const MAX_TIMESKEW_SAMPLES: usize = 512;
+const TIMESKEW_WINDOW_SECS: u64 = 15 * 60;
+
+static ME_SELFTEST_STATE: OnceLock<Mutex<MeSelftestState>> = OnceLock::new();
+
+fn state() -> &'static Mutex<MeSelftestState> {
+    ME_SELFTEST_STATE.get_or_init(|| Mutex::new(MeSelftestState::default()))
+}
+
+pub(crate) fn record_bnd_status(
+    addr_status: BndAddrStatus,
+    port_status: BndPortStatus,
+    last_addr: Option<SocketAddr>,
+) {
+    let now_epoch_secs = now_epoch_secs();
+    let Ok(mut guard) = state().lock() else {
+        return;
+    };
+    guard.bnd_addr_status = addr_status;
+    guard.bnd_port_status = port_status;
+    guard.bnd_last_addr = last_addr;
+    guard.bnd_last_seen_epoch_secs = Some(now_epoch_secs);
+}
+
+pub(crate) fn bnd_snapshot() -> MeBndSnapshot {
+    let now_epoch_secs = now_epoch_secs();
+    let Ok(guard) = state().lock() else {
+        return MeBndSnapshot {
+            addr_status: BndAddrStatus::Error.as_str(),
+            port_status: BndPortStatus::Error.as_str(),
+            last_addr: None,
+            last_seen_age_secs: None,
+        };
+    };
+    MeBndSnapshot {
+        addr_status: guard.bnd_addr_status.as_str(),
+        port_status: guard.bnd_port_status.as_str(),
+        last_addr: guard.bnd_last_addr,
+        last_seen_age_secs: guard
+            .bnd_last_seen_epoch_secs
+            .map(|value| now_epoch_secs.saturating_sub(value)),
+    }
+}
+
+pub(crate) fn record_upstream_bnd_status(
+    upstream_id: usize,
+    addr_status: BndAddrStatus,
+    port_status: BndPortStatus,
+    last_addr: Option<SocketAddr>,
+    last_ip: Option<IpAddr>,
+) {
+    let now_epoch_secs = now_epoch_secs();
+    let Ok(mut guard) = state().lock() else {
+        return;
+    };
+    guard.upstream_bnd.insert(
+        upstream_id,
+        UpstreamBndState {
+            addr_status,
+            port_status,
+            last_addr,
+            last_ip,
+            last_seen_epoch_secs: Some(now_epoch_secs),
+        },
+    );
+}
+
+pub(crate) fn upstream_bnd_snapshots() -> Vec<MeUpstreamBndSnapshot> {
+    let now_epoch_secs = now_epoch_secs();
+    let Ok(guard) = state().lock() else {
+        return Vec::new();
+    };
+    let mut out = Vec::with_capacity(guard.upstream_bnd.len());
+    for (upstream_id, entry) in &guard.upstream_bnd {
+        out.push(MeUpstreamBndSnapshot {
+            upstream_id: *upstream_id,
+            addr_status: entry.addr_status.as_str(),
+            port_status: entry.port_status.as_str(),
+            last_addr: entry.last_addr,
+            last_ip: entry.last_ip,
+            last_seen_age_secs: entry
+                .last_seen_epoch_secs
+                .map(|value| now_epoch_secs.saturating_sub(value)),
+        });
+    }
+    out.sort_by_key(|entry| entry.upstream_id);
+    out
+}
+
+pub(crate) fn record_timeskew_sample(source: &'static str, skew_secs: u64) {
+    let now_epoch_secs = now_epoch_secs();
+    let Ok(mut guard) = state().lock() else {
+        return;
+    };
+    guard.timeskew_samples.push_back(MeTimeskewSample {
+        ts_epoch_secs: now_epoch_secs,
+        skew_secs,
+        source,
+    });
+    while guard.timeskew_samples.len() > MAX_TIMESKEW_SAMPLES {
+        guard.timeskew_samples.pop_front();
+    }
+    let cutoff = now_epoch_secs.saturating_sub(TIMESKEW_WINDOW_SECS * 2);
+    while guard
+        .timeskew_samples
+        .front()
+        .is_some_and(|sample| sample.ts_epoch_secs < cutoff)
+    {
+        guard.timeskew_samples.pop_front();
+    }
+}
+
+pub(crate) fn timeskew_snapshot() -> MeTimeskewSnapshot {
+    let now_epoch_secs = now_epoch_secs();
+    let Ok(guard) = state().lock() else {
+        return MeTimeskewSnapshot::default();
+    };
+
+    let mut max_skew_secs_15m = None;
+    let mut samples_15m = 0usize;
+    let window_start = now_epoch_secs.saturating_sub(TIMESKEW_WINDOW_SECS);
+    for sample in &guard.timeskew_samples {
+        if sample.ts_epoch_secs < window_start {
+            continue;
+        }
+        samples_15m = samples_15m.saturating_add(1);
+        max_skew_secs_15m = Some(max_skew_secs_15m.unwrap_or(0).max(sample.skew_secs));
+    }
+
+    let (last_skew_secs, last_source, last_seen_age_secs) =
+        if let Some(last) = guard.timeskew_samples.back() {
+            (
+                Some(last.skew_secs),
+                Some(last.source),
+                Some(now_epoch_secs.saturating_sub(last.ts_epoch_secs)),
+            )
+        } else {
+            (None, None, None)
+        };
+
+    MeTimeskewSnapshot {
+        max_skew_secs_15m,
+        samples_15m,
+        last_skew_secs,
+        last_source,
+        last_seen_age_secs,
+    }
+}
+
+fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}

src/transport/middle_proxy/send.rs

@@ -9,7 +9,7 @@ use bytes::Bytes;
 use tokio::sync::mpsc::error::TrySendError;
 use tracing::{debug, warn};
 
-use crate::config::MeRouteNoWriterMode;
+use crate::config::{MeRouteNoWriterMode, MeWriterPickMode};
 use crate::error::{ProxyError, Result};
 use crate::network::IpFamily;
 use crate::protocol::constants::{RPC_CLOSE_CONN_U32, RPC_CLOSE_EXT_U32};
@@ -24,6 +24,10 @@ use super::registry::ConnMeta;
 const IDLE_WRITER_PENALTY_MID_SECS: u64 = 45;
 const IDLE_WRITER_PENALTY_HIGH_SECS: u64 = 55;
 const HYBRID_GLOBAL_BURST_PERIOD_ROUNDS: u32 = 4;
+const PICK_PENALTY_WARM: u64 = 200;
+const PICK_PENALTY_DRAINING: u64 = 600;
+const PICK_PENALTY_STALE: u64 = 300;
+const PICK_PENALTY_DEGRADED: u64 = 250;
 
 impl MePool {
     /// Send RPC_PROXY_REQ. `tag_override`: per-user ad_tag (from access.user_ad_tags); if None, uses pool default.
@@ -38,20 +42,30 @@ impl MePool {
         tag_override: Option<&[u8]>,
     ) -> Result<()> {
         let tag = tag_override.or(self.proxy_tag.as_deref());
-        let payload = build_proxy_req_payload(
-            conn_id,
-            client_addr,
-            our_addr,
-            data,
-            tag,
-            proto_flags,
-        );
-        let meta = ConnMeta {
+        let fallback_meta = ConnMeta {
             target_dc,
             client_addr,
             our_addr,
             proto_flags,
         };
+        let build_routed_payload = |effective_our_addr: SocketAddr| {
+            (
+                build_proxy_req_payload(
+                    conn_id,
+                    client_addr,
+                    effective_our_addr,
+                    data,
+                    tag,
+                    proto_flags,
+                ),
+                ConnMeta {
+                    target_dc,
+                    client_addr,
+                    our_addr: effective_our_addr,
+                    proto_flags,
+                },
+            )
+        };
         let no_writer_mode =
             MeRouteNoWriterMode::from_u8(self.me_route_no_writer_mode.load(Ordering::Relaxed));
         let (routed_dc, unknown_target_dc) = self
@@ -66,8 +80,14 @@ impl MePool {
         let mut hybrid_wait_current = hybrid_wait_step;
 
         loop {
+            let current_meta = self
+                .registry
+                .get_meta(conn_id)
+                .await
+                .unwrap_or_else(|| fallback_meta.clone());
+            let (current_payload, _) = build_routed_payload(current_meta.our_addr);
             if let Some(current) = self.registry.get_writer(conn_id).await {
-                match current.tx.try_send(WriterCommand::Data(payload.clone())) {
+                match current.tx.try_send(WriterCommand::Data(current_payload.clone())) {
                     Ok(()) => return Ok(()),
                     Err(TrySendError::Full(cmd)) => {
                         if current.tx.send(cmd).await.is_ok() {
@@ -181,6 +201,7 @@ impl MePool {
                     .await;
             }
             if candidate_indices.is_empty() {
+                let pick_mode = self.writer_pick_mode();
                 match no_writer_mode {
                     MeRouteNoWriterMode::AsyncRecoveryFailfast => {
                         let deadline = *no_writer_deadline.get_or_insert_with(|| {
@@ -196,6 +217,7 @@ impl MePool {
                         if self.wait_for_candidate_until(routed_dc, deadline).await {
                             continue;
                         }
+                        self.stats.increment_me_writer_pick_no_candidate_total(pick_mode);
                         self.stats.increment_me_no_writer_failfast_total();
                         return Err(ProxyError::Proxy(
                             "No ME writers available for target DC in failfast window".into(),
@@ -209,10 +231,12 @@ impl MePool {
                             if self.wait_for_candidate_until(routed_dc, deadline).await {
                                 continue;
                             }
+                            self.stats.increment_me_writer_pick_no_candidate_total(pick_mode);
                             self.stats.increment_me_no_writer_failfast_total();
                             return Err(ProxyError::Proxy("No ME writers available for target DC".into()));
                         }
                         if emergency_attempts >= self.me_route_inline_recovery_attempts.max(1) {
+                            self.stats.increment_me_writer_pick_no_candidate_total(pick_mode);
                             self.stats.increment_me_no_writer_failfast_total();
                             return Err(ProxyError::Proxy("No ME writers available for target DC".into()));
                         }
@@ -237,6 +261,7 @@ impl MePool {
                                 .await;
                         }
                         if candidate_indices.is_empty() {
+                            self.stats.increment_me_writer_pick_no_candidate_total(pick_mode);
                             return Err(ProxyError::Proxy("No ME writers available for target DC".into()));
                         }
                     }
@@ -259,6 +284,8 @@ impl MePool {
                 }
             }
             hybrid_wait_current = hybrid_wait_step;
+            let pick_mode = self.writer_pick_mode();
+            let pick_sample_size = self.writer_pick_sample_size();
             let writer_ids: Vec<u64> = candidate_indices
                 .iter()
                 .map(|idx| writers_snapshot[*idx].id)
@@ -268,72 +295,94 @@ impl MePool {
                 .writer_idle_since_for_writer_ids(&writer_ids)
                 .await;
             let now_epoch_secs = Self::now_epoch_secs();
-
-            if self.me_deterministic_writer_sort.load(Ordering::Relaxed) {
-                candidate_indices.sort_by(|lhs, rhs| {
-                    let left = &writers_snapshot[*lhs];
-                    let right = &writers_snapshot[*rhs];
-                    let left_key = (
-                        self.writer_contour_rank_for_selection(left),
-                        (left.generation < self.current_generation()) as usize,
-                        left.degraded.load(Ordering::Relaxed) as usize,
-                        self.writer_idle_rank_for_selection(
-                            left,
-                            &writer_idle_since,
-                            now_epoch_secs,
-                        ),
-                        Reverse(left.tx.capacity()),
-                        left.addr,
-                        left.id,
-                    );
-                    let right_key = (
-                        self.writer_contour_rank_for_selection(right),
-                        (right.generation < self.current_generation()) as usize,
-                        right.degraded.load(Ordering::Relaxed) as usize,
-                        self.writer_idle_rank_for_selection(
-                            right,
-                            &writer_idle_since,
-                            now_epoch_secs,
-                        ),
-                        Reverse(right.tx.capacity()),
-                        right.addr,
-                        right.id,
-                    );
-                    left_key.cmp(&right_key)
-                });
-            } else {
-                candidate_indices.sort_by_key(|idx| {
-                    let w = &writers_snapshot[*idx];
-                    let degraded = w.degraded.load(Ordering::Relaxed);
-                    let stale = (w.generation < self.current_generation()) as usize;
-                    (
-                        self.writer_contour_rank_for_selection(w),
-                        stale,
-                        degraded as usize,
-                        self.writer_idle_rank_for_selection(
-                            w,
-                            &writer_idle_since,
-                            now_epoch_secs,
-                        ),
-                        Reverse(w.tx.capacity()),
-                    )
-                });
-            }
-
             let start = self.rr.fetch_add(1, Ordering::Relaxed) as usize % candidate_indices.len();
+            let ordered_candidate_indices = if pick_mode == MeWriterPickMode::P2c {
+                self.p2c_ordered_candidate_indices(
+                    &candidate_indices,
+                    &writers_snapshot,
+                    &writer_idle_since,
+                    now_epoch_secs,
+                    start,
+                    pick_sample_size,
+                )
+            } else {
+                if self.me_deterministic_writer_sort.load(Ordering::Relaxed) {
+                    candidate_indices.sort_by(|lhs, rhs| {
+                        let left = &writers_snapshot[*lhs];
+                        let right = &writers_snapshot[*rhs];
+                        let left_key = (
+                            self.writer_contour_rank_for_selection(left),
+                            (left.generation < self.current_generation()) as usize,
+                            left.degraded.load(Ordering::Relaxed) as usize,
+                            self.writer_idle_rank_for_selection(
+                                left,
+                                &writer_idle_since,
+                                now_epoch_secs,
+                            ),
+                            Reverse(left.tx.capacity()),
+                            left.addr,
+                            left.id,
+                        );
+                        let right_key = (
+                            self.writer_contour_rank_for_selection(right),
+                            (right.generation < self.current_generation()) as usize,
+                            right.degraded.load(Ordering::Relaxed) as usize,
+                            self.writer_idle_rank_for_selection(
+                                right,
+                                &writer_idle_since,
+                                now_epoch_secs,
+                            ),
+                            Reverse(right.tx.capacity()),
+                            right.addr,
+                            right.id,
+                        );
+                        left_key.cmp(&right_key)
+                    });
+                } else {
+                    candidate_indices.sort_by_key(|idx| {
+                        let w = &writers_snapshot[*idx];
+                        let degraded = w.degraded.load(Ordering::Relaxed);
+                        let stale = (w.generation < self.current_generation()) as usize;
+                        (
+                            self.writer_contour_rank_for_selection(w),
+                            stale,
+                            degraded as usize,
+                            self.writer_idle_rank_for_selection(
+                                w,
+                                &writer_idle_since,
+                                now_epoch_secs,
+                            ),
+                            Reverse(w.tx.capacity()),
+                        )
+                    });
+                }
+
+                let mut ordered = Vec::<usize>::with_capacity(candidate_indices.len());
+                for offset in 0..candidate_indices.len() {
+                    ordered.push(candidate_indices[(start + offset) % candidate_indices.len()]);
+                }
+                ordered
+            };
             let mut fallback_blocking_idx: Option<usize> = None;
 
-            for offset in 0..candidate_indices.len() {
-                let idx = candidate_indices[(start + offset) % candidate_indices.len()];
+            for idx in ordered_candidate_indices {
                 let w = &writers_snapshot[idx];
                 if !self.writer_accepts_new_binding(w) {
                     continue;
                 }
+                let effective_our_addr = SocketAddr::new(w.source_ip, our_addr.port());
+                let (payload, meta) = build_routed_payload(effective_our_addr);
                 match w.tx.try_send(WriterCommand::Data(payload.clone())) {
                     Ok(()) => {
-                        self.registry
-                            .bind_writer(conn_id, w.id, w.tx.clone(), meta.clone())
-                            .await;
+                        self.stats.increment_me_writer_pick_success_try_total(pick_mode);
+                        if !self.registry.bind_writer(conn_id, w.id, meta).await {
+                            debug!(
+                                conn_id,
+                                writer_id = w.id,
+                                "ME writer disappeared before bind commit, retrying"
+                            );
+                            continue;
+                        }
                         if w.generation < self.current_generation() {
                             self.stats.increment_pool_stale_pick_total();
                             debug!(
@@ -352,6 +401,7 @@ impl MePool {
                         }
                     }
                     Err(TrySendError::Closed(_)) => {
+                        self.stats.increment_me_writer_pick_closed_total(pick_mode);
                         warn!(writer_id = w.id, "ME writer channel closed");
                         self.remove_writer_and_close_clients(w.id).await;
                         continue;
@@ -360,24 +410,37 @@ impl MePool {
             }
 
             let Some(blocking_idx) = fallback_blocking_idx else {
+                self.stats.increment_me_writer_pick_full_total(pick_mode);
                 continue;
             };
 
             let w = writers_snapshot[blocking_idx].clone();
             if !self.writer_accepts_new_binding(&w) {
+                self.stats.increment_me_writer_pick_full_total(pick_mode);
                 continue;
             }
+            self.stats.increment_me_writer_pick_blocking_fallback_total();
+            let effective_our_addr = SocketAddr::new(w.source_ip, our_addr.port());
+            let (payload, meta) = build_routed_payload(effective_our_addr);
             match w.tx.send(WriterCommand::Data(payload.clone())).await {
                 Ok(()) => {
-                    self.registry
-                        .bind_writer(conn_id, w.id, w.tx.clone(), meta.clone())
-                        .await;
+                    self.stats
+                        .increment_me_writer_pick_success_fallback_total(pick_mode);
+                    if !self.registry.bind_writer(conn_id, w.id, meta).await {
+                        debug!(
+                            conn_id,
+                            writer_id = w.id,
+                            "ME writer disappeared before fallback bind commit, retrying"
+                        );
+                        continue;
+                    }
                     if w.generation < self.current_generation() {
                         self.stats.increment_pool_stale_pick_total();
                     }
                     return Ok(());
                 }
                 Err(_) => {
+                    self.stats.increment_me_writer_pick_closed_total(pick_mode);
                     warn!(writer_id = w.id, "ME writer channel closed (blocking)");
                     self.remove_writer_and_close_clients(w.id).await;
                 }
@@ -480,31 +543,7 @@ impl MePool {
     }
 
     async fn endpoint_candidates_for_target_dc(&self, routed_dc: i32) -> Vec<SocketAddr> {
-        let mut preferred = Vec::<SocketAddr>::new();
-        let mut seen = HashSet::<SocketAddr>::new();
-
-        for family in self.family_order() {
-            let map_guard = match family {
-                IpFamily::V4 => self.proxy_map_v4.read().await,
-                IpFamily::V6 => self.proxy_map_v6.read().await,
-            };
-            let mut family_selected = Vec::<SocketAddr>::new();
-            if let Some(addrs) = map_guard.get(&routed_dc) {
-                for (ip, port) in addrs {
-                    family_selected.push(SocketAddr::new(*ip, *port));
-                }
-            }
-            for addr in family_selected {
-                if seen.insert(addr) {
-                    preferred.push(addr);
-                }
-            }
-            if !preferred.is_empty() && !self.decision.effective_multipath {
-                break;
-            }
-        }
-
-        preferred
+        self.preferred_endpoints_for_dc(routed_dc).await
     }
 
     async fn maybe_trigger_hybrid_recovery(
@@ -591,28 +630,7 @@ impl MePool {
         routed_dc: i32,
         include_warm: bool,
     ) -> Vec<usize> {
-        let mut preferred = HashSet::<SocketAddr>::new();
-
-        for family in self.family_order() {
-            let map_guard = match family {
-                IpFamily::V4 => self.proxy_map_v4.read().await,
-                IpFamily::V6 => self.proxy_map_v6.read().await,
-            };
-            let mut family_selected = Vec::<SocketAddr>::new();
-            if let Some(v) = map_guard.get(&routed_dc) {
-                family_selected.extend(v.iter().map(|(ip, port)| SocketAddr::new(*ip, *port)));
-            }
-            for endpoint in family_selected {
-                preferred.insert(endpoint);
-            }
-
-            drop(map_guard);
-
-            if !preferred.is_empty() && !self.decision.effective_multipath {
-                break;
-            }
-        }
-
+        let preferred = self.preferred_endpoints_for_dc(routed_dc).await;
         if preferred.is_empty() {
             return Vec::new();
         }
@@ -622,7 +640,7 @@ impl MePool {
             if !self.writer_eligible_for_selection(w, include_warm) {
                 continue;
             }
-            if w.writer_dc == routed_dc && preferred.contains(&w.addr) {
+            if w.writer_dc == routed_dc && preferred.iter().any(|endpoint| *endpoint == w.addr) {
                 out.push(idx);
             }
         }
@@ -671,4 +689,87 @@ impl MePool {
             0
         }
     }
+
+    fn writer_pick_score(
+        &self,
+        writer: &super::pool::MeWriter,
+        idle_since_by_writer: &HashMap<u64, u64>,
+        now_epoch_secs: u64,
+    ) -> u64 {
+        let contour_penalty = match WriterContour::from_u8(writer.contour.load(Ordering::Relaxed)) {
+            WriterContour::Active => 0,
+            WriterContour::Warm => PICK_PENALTY_WARM,
+            WriterContour::Draining => PICK_PENALTY_DRAINING,
+        };
+        let stale_penalty = if writer.generation < self.current_generation() {
+            PICK_PENALTY_STALE
+        } else {
+            0
+        };
+        let degraded_penalty = if writer.degraded.load(Ordering::Relaxed) {
+            PICK_PENALTY_DEGRADED
+        } else {
+            0
+        };
+        let idle_penalty =
+            (self.writer_idle_rank_for_selection(writer, idle_since_by_writer, now_epoch_secs) as u64)
+                * 100;
+        let queue_cap = self.writer_cmd_channel_capacity.max(1) as u64;
+        let queue_remaining = writer.tx.capacity() as u64;
+        let queue_used = queue_cap.saturating_sub(queue_remaining.min(queue_cap));
+        let queue_util_pct = queue_used.saturating_mul(100) / queue_cap;
+        let queue_penalty = queue_util_pct.saturating_mul(4);
+        let rtt_penalty = ((writer.rtt_ema_ms_x10.load(Ordering::Relaxed) as u64).saturating_add(5) / 10)
+            .min(400);
+
+        contour_penalty
+            .saturating_add(stale_penalty)
+            .saturating_add(degraded_penalty)
+            .saturating_add(idle_penalty)
+            .saturating_add(queue_penalty)
+            .saturating_add(rtt_penalty)
+    }
+
+    fn p2c_ordered_candidate_indices(
+        &self,
+        candidate_indices: &[usize],
+        writers_snapshot: &[super::pool::MeWriter],
+        idle_since_by_writer: &HashMap<u64, u64>,
+        now_epoch_secs: u64,
+        start: usize,
+        sample_size: usize,
+    ) -> Vec<usize> {
+        let total = candidate_indices.len();
+        if total == 0 {
+            return Vec::new();
+        }
+
+        let mut sampled = Vec::<usize>::with_capacity(sample_size.min(total));
+        let mut seen = HashSet::<usize>::with_capacity(total);
+        for offset in 0..sample_size.min(total) {
+            let idx = candidate_indices[(start + offset) % total];
+            if seen.insert(idx) {
+                sampled.push(idx);
+            }
+        }
+
+        sampled.sort_by_key(|idx| {
+            let writer = &writers_snapshot[*idx];
+            (
+                self.writer_pick_score(writer, idle_since_by_writer, now_epoch_secs),
+                writer.addr,
+                writer.id,
+            )
+        });
+
+        let mut ordered = Vec::<usize>::with_capacity(total);
+        ordered.extend(sampled.iter().copied());
+        for offset in 0..total {
+            let idx = candidate_indices[(start + offset) % total];
+            if seen.insert(idx) {
+                ordered.push(idx);
+            }
+        }
+        ordered
+    }
 }

src/transport/socket.rs

@@ -1,6 +1,8 @@
 //! TCP Socket Configuration
 
+#[cfg(target_os = "linux")]
 use std::collections::HashSet;
+#[cfg(target_os = "linux")]
 use std::fs;
 use std::io::Result;
 use std::net::{SocketAddr, IpAddr};
@@ -44,6 +46,7 @@ pub fn configure_tcp_socket(
 pub fn configure_client_socket(
     stream: &TcpStream,
     keepalive_secs: u64,
+    #[cfg_attr(not(target_os = "linux"), allow(unused_variables))]
     ack_timeout_secs: u64,
 ) -> Result<()> {
     let socket = socket2::SockRef::from(stream);
@@ -65,17 +68,27 @@ pub fn configure_client_socket(
     // is implemented in relay_bidirectional instead
     #[cfg(target_os = "linux")]
     {
+        use std::io::{Error, ErrorKind};
         use std::os::unix::io::AsRawFd;
+
         let fd = stream.as_raw_fd();
-        let timeout_ms = (ack_timeout_secs * 1000) as libc::c_int;
-        unsafe {
+        let timeout_ms_u64 = ack_timeout_secs
+            .checked_mul(1000)
+            .ok_or_else(|| Error::new(ErrorKind::InvalidInput, "ack_timeout_secs is too large"))?;
+        let timeout_ms = i32::try_from(timeout_ms_u64)
+            .map_err(|_| Error::new(ErrorKind::InvalidInput, "ack_timeout_secs exceeds TCP_USER_TIMEOUT range"))?;
+
+        let rc = unsafe {
             libc::setsockopt(
                 fd,
                 libc::IPPROTO_TCP,
                 libc::TCP_USER_TIMEOUT,
-                &timeout_ms as *const _ as *const libc::c_void,
+                &timeout_ms as *const libc::c_int as *const libc::c_void,
                 std::mem::size_of::<libc::c_int>() as libc::socklen_t,
-            );
+            )
+        };
+        if rc != 0 {
+            return Err(Error::last_os_error());
         }
     }
     
@@ -373,6 +386,7 @@ fn listening_inodes_for_port(addr: SocketAddr) -> HashSet<u64> {
 mod tests {
     use super::*;
     use std::io::ErrorKind;
+    use tokio::io::{AsyncReadExt, AsyncWriteExt};
     use tokio::net::TcpListener;
     
     #[tokio::test]
@@ -396,6 +410,142 @@ mod tests {
             panic!("configure_tcp_socket failed: {e}");
         }
     }
+
+    #[tokio::test]
+    async fn test_configure_client_socket() {
+        let listener = match TcpListener::bind("127.0.0.1:0").await {
+            Ok(l) => l,
+            Err(e) if e.kind() == ErrorKind::PermissionDenied => return,
+            Err(e) => panic!("bind failed: {e}"),
+        };
+        let addr = match listener.local_addr() {
+            Ok(addr) => addr,
+            Err(e) => panic!("local_addr failed: {e}"),
+        };
+
+        let stream = match TcpStream::connect(addr).await {
+            Ok(s) => s,
+            Err(e) if e.kind() == ErrorKind::PermissionDenied => return,
+            Err(e) => panic!("connect failed: {e}"),
+        };
+
+        if let Err(e) = configure_client_socket(&stream, 30, 30) {
+            if e.kind() == ErrorKind::PermissionDenied {
+                return;
+            }
+            panic!("configure_client_socket failed: {e}");
+        }
+    }
+
+    #[tokio::test]
+    async fn test_configure_client_socket_zero_ack_timeout() {
+        let listener = match TcpListener::bind("127.0.0.1:0").await {
+            Ok(l) => l,
+            Err(e) if e.kind() == ErrorKind::PermissionDenied => return,
+            Err(e) => panic!("bind failed: {e}"),
+        };
+        let addr = match listener.local_addr() {
+            Ok(addr) => addr,
+            Err(e) => panic!("local_addr failed: {e}"),
+        };
+
+        let stream = match TcpStream::connect(addr).await {
+            Ok(s) => s,
+            Err(e) if e.kind() == ErrorKind::PermissionDenied => return,
+            Err(e) => panic!("connect failed: {e}"),
+        };
+
+        if let Err(e) = configure_client_socket(&stream, 30, 0) {
+            if e.kind() == ErrorKind::PermissionDenied {
+                return;
+            }
+            panic!("configure_client_socket with zero ack timeout failed: {e}");
+        }
+    }
+
+    #[tokio::test]
+    async fn test_configure_client_socket_roundtrip_io() {
+        let listener = match TcpListener::bind("127.0.0.1:0").await {
+            Ok(l) => l,
+            Err(e) if e.kind() == ErrorKind::PermissionDenied => return,
+            Err(e) => panic!("bind failed: {e}"),
+        };
+        let addr = match listener.local_addr() {
+            Ok(addr) => addr,
+            Err(e) => panic!("local_addr failed: {e}"),
+        };
+
+        let server_task = tokio::spawn(async move {
+            let (mut accepted, _) = match listener.accept().await {
+                Ok(v) => v,
+                Err(e) => panic!("accept failed: {e}"),
+            };
+            let mut payload = [0u8; 4];
+            if let Err(e) = accepted.read_exact(&mut payload).await {
+                panic!("server read_exact failed: {e}");
+            }
+            if let Err(e) = accepted.write_all(b"pong").await {
+                panic!("server write_all failed: {e}");
+            }
+            payload
+        });
+
+        let mut stream = match TcpStream::connect(addr).await {
+            Ok(s) => s,
+            Err(e) if e.kind() == ErrorKind::PermissionDenied => return,
+            Err(e) => panic!("connect failed: {e}"),
+        };
+
+        if let Err(e) = configure_client_socket(&stream, 30, 30) {
+            if e.kind() == ErrorKind::PermissionDenied {
+                return;
+            }
+            panic!("configure_client_socket failed: {e}");
+        }
+
+        if let Err(e) = stream.write_all(b"ping").await {
+            panic!("client write_all failed: {e}");
+        }
+
+        let mut reply = [0u8; 4];
+        if let Err(e) = stream.read_exact(&mut reply).await {
+            panic!("client read_exact failed: {e}");
+        }
+        assert_eq!(&reply, b"pong");
+
+        let server_seen = match server_task.await {
+            Ok(value) => value,
+            Err(e) => panic!("server task join failed: {e}"),
+        };
+        assert_eq!(&server_seen, b"ping");
+    }
+
+    #[cfg(target_os = "linux")]
+    #[tokio::test]
+    async fn test_configure_client_socket_ack_timeout_overflow_rejected() {
+        let listener = match TcpListener::bind("127.0.0.1:0").await {
+            Ok(l) => l,
+            Err(e) if e.kind() == ErrorKind::PermissionDenied => return,
+            Err(e) => panic!("bind failed: {e}"),
+        };
+        let addr = match listener.local_addr() {
+            Ok(addr) => addr,
+            Err(e) => panic!("local_addr failed: {e}"),
+        };
+
+        let stream = match TcpStream::connect(addr).await {
+            Ok(s) => s,
+            Err(e) if e.kind() == ErrorKind::PermissionDenied => return,
+            Err(e) => panic!("connect failed: {e}"),
+        };
+
+        let too_large_secs = (i32::MAX as u64 / 1000) + 1;
+        let err = match configure_client_socket(&stream, 30, too_large_secs) {
+            Ok(()) => panic!("expected overflow validation error"),
+            Err(e) => e,
+        };
+        assert_eq!(err.kind(), ErrorKind::InvalidInput);
+    }
     
     #[test]
     fn test_normalize_ip() {

src/transport/upstream.rs

@@ -213,6 +213,7 @@ pub struct UpstreamApiPolicySnapshot {
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct UpstreamEgressInfo {
+    pub upstream_id: usize,
     pub route_kind: UpstreamRouteKind,
     pub local_addr: Option<SocketAddr>,
     pub direct_bind_ip: Option<IpAddr>,
@@ -389,7 +390,7 @@ impl UpstreamManager {
         out
     }
 
-    fn resolve_bind_address(
+    pub(crate) fn resolve_bind_address(
         interface: &Option<String>,
         bind_addresses: &Option<Vec<String>>,
         target: SocketAddr,
@@ -398,7 +399,7 @@ impl UpstreamManager {
     ) -> Option<IpAddr> {
         let want_ipv6 = target.is_ipv6();
 
-        if let Some(addrs) = bind_addresses {
+        if let Some(addrs) = bind_addresses.as_ref().filter(|v| !v.is_empty()) {
             let mut candidates: Vec<IpAddr> = addrs
                 .iter()
                 .filter_map(|s| s.parse::<IpAddr>().ok())
@@ -430,7 +431,7 @@ impl UpstreamManager {
                         warn!(
                             interface = %iface,
                             target = %target,
-                            "Configured interface has no addresses for target family; falling back to direct connect without bind"
+                            "Configured interface has no addresses for target family"
                         );
                         candidates.clear();
                     }
@@ -453,10 +454,11 @@ impl UpstreamManager {
                 warn!(
                     interface = interface.as_deref().unwrap_or(""),
                     target = %target,
-                    "No valid bind_addresses left for interface; falling back to direct connect without bind"
+                    "No valid bind_addresses left for interface"
                 );
-                return None;
             }
+
+            return None;
         }
 
         if let Some(iface) = interface {
@@ -672,7 +674,7 @@ impl UpstreamManager {
             self.stats.increment_upstream_connect_attempt_total();
             let start = Instant::now();
             match self
-                .connect_via_upstream(&upstream, target, bind_rr.clone(), attempt_timeout)
+                .connect_via_upstream(idx, &upstream, target, bind_rr.clone(), attempt_timeout)
                 .await
             {
                 Ok((stream, egress)) => {
@@ -779,6 +781,7 @@ impl UpstreamManager {
 
     async fn connect_via_upstream(
         &self,
+        upstream_id: usize,
         config: &UpstreamConfig,
         target: SocketAddr,
         bind_rr: Option<Arc<AtomicUsize>>,
@@ -793,6 +796,13 @@ impl UpstreamManager {
                     bind_rr.as_deref(),
                     true,
                 );
+                if bind_ip.is_none()
+                    && bind_addresses.as_ref().is_some_and(|v| !v.is_empty())
+                {
+                    return Err(ProxyError::Config(format!(
+                        "No valid bind_addresses for target family {target}"
+                    )));
+                }
 
                 let socket = create_outgoing_socket_bound(target, bind_ip)?;
                 if let Some(ip) = bind_ip {
@@ -828,6 +838,7 @@ impl UpstreamManager {
                 Ok((
                     stream,
                     UpstreamEgressInfo {
+                        upstream_id,
                         route_kind: UpstreamRouteKind::Direct,
                         local_addr,
                         direct_bind_ip: bind_ip,
@@ -906,6 +917,7 @@ impl UpstreamManager {
                 Ok((
                     stream,
                     UpstreamEgressInfo {
+                        upstream_id,
                         route_kind: UpstreamRouteKind::Socks4,
                         local_addr,
                         direct_bind_ip: None,
@@ -986,6 +998,7 @@ impl UpstreamManager {
                 Ok((
                     stream,
                     UpstreamEgressInfo {
+                        upstream_id,
                         route_kind: UpstreamRouteKind::Socks5,
                         local_addr,
                         direct_bind_ip: None,
@@ -1048,7 +1061,7 @@ impl UpstreamManager {
 
                     let result = tokio::time::timeout(
                         Duration::from_secs(DC_PING_TIMEOUT_SECS),
-                        self.ping_single_dc(upstream_config, Some(bind_rr.clone()), addr_v6)
+                        self.ping_single_dc(*upstream_idx, upstream_config, Some(bind_rr.clone()), addr_v6)
                     ).await;
 
                     let ping_result = match result {
@@ -1099,7 +1112,7 @@ impl UpstreamManager {
 
                     let result = tokio::time::timeout(
                         Duration::from_secs(DC_PING_TIMEOUT_SECS),
-                        self.ping_single_dc(upstream_config, Some(bind_rr.clone()), addr_v4)
+                        self.ping_single_dc(*upstream_idx, upstream_config, Some(bind_rr.clone()), addr_v4)
                     ).await;
 
                     let ping_result = match result {
@@ -1162,7 +1175,7 @@ impl UpstreamManager {
                             }
                             let result = tokio::time::timeout(
                                 Duration::from_secs(DC_PING_TIMEOUT_SECS),
-                                self.ping_single_dc(upstream_config, Some(bind_rr.clone()), addr)
+                                self.ping_single_dc(*upstream_idx, upstream_config, Some(bind_rr.clone()), addr)
                             ).await;
 
                             let ping_result = match result {
@@ -1233,6 +1246,7 @@ impl UpstreamManager {
 
     async fn ping_single_dc(
         &self,
+        upstream_id: usize,
         config: &UpstreamConfig,
         bind_rr: Option<Arc<AtomicUsize>>,
         target: SocketAddr,
@@ -1240,6 +1254,7 @@ impl UpstreamManager {
         let start = Instant::now();
         let _ = self
             .connect_via_upstream(
+                upstream_id,
                 config,
                 target,
                 bind_rr,
@@ -1418,6 +1433,7 @@ impl UpstreamManager {
                             let result = tokio::time::timeout(
                                 Duration::from_secs(HEALTH_CHECK_CONNECT_TIMEOUT_SECS),
                                 self.connect_via_upstream(
+                                    i,
                                     &config,
                                     endpoint,
                                     Some(bind_rr.clone()),
@@ -1634,4 +1650,32 @@ mod tests {
         };
         assert!(!UpstreamManager::is_hard_connect_error(&error));
     }
+
+    #[test]
+    fn resolve_bind_address_prefers_explicit_bind_ip() {
+        let target = "203.0.113.10:443".parse::<SocketAddr>().unwrap();
+        let bind = UpstreamManager::resolve_bind_address(
+            &Some("198.51.100.20".to_string()),
+            &Some(vec!["198.51.100.10".to_string()]),
+            target,
+            None,
+            true,
+        );
+
+        assert_eq!(bind, Some("198.51.100.10".parse::<IpAddr>().unwrap()));
+    }
+
+    #[test]
+    fn resolve_bind_address_does_not_fallback_to_interface_when_bind_addresses_present() {
+        let target = "203.0.113.10:443".parse::<SocketAddr>().unwrap();
+        let bind = UpstreamManager::resolve_bind_address(
+            &Some("198.51.100.20".to_string()),
+            &Some(vec!["2001:db8::10".to_string()]),
+            target,
+            None,
+            true,
+        );
+
+        assert_eq!(bind, None);
+    }
 }

telemt.service

@@ -1,13 +0,0 @@
-[Unit]
-Description=Telemt
-After=network.target
-
-[Service]
-Type=simple
-WorkingDirectory=/bin
-ExecStart=/bin/telemt /etc/telemt.toml
-Restart=on-failure
-LimitNOFILE=65536
-
-[Install]
-WantedBy=multi-user.target