jerryproxy 0.1.0__tar.gz → 0.2.0__tar.gz

{jerryproxy-0.1.0 → jerryproxy-0.2.0}/MANIFEST.in

@@ -1,7 +1,6 @@
 include LICENSE
 include THIRD_PARTY_LICENSES.md
 include README.md
-include RELEASE_NOTES.md
 include auto_rst.py
 include auto_rst_top_index.py
 include requirements.txt

{jerryproxy-0.1.0/jerryproxy.egg-info → jerryproxy-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: jerryproxy
-Version: 0.1.0
+Version: 0.2.0
 Summary: An out-of-the-box multi-backend proxy CLI and backend manager.
 Home-page: https://github.com/narugo1992/jerryproxy
 Author: narugo1992
@@ -46,7 +46,7 @@ switching, and eventually orchestrating multiple external proxy backends. The
 PyPI distribution, Python import, GitHub repository, CLI command, and default
 home directory all use the same name: `jerryproxy`.
 
-> **0.1.0 alpha-quality release:** the first runtime slice is implemented: bounded
+> **0.2.0 release preparation (alpha quality):** the current runtime slice implements bounded
 > `V2RAY_SUBSCRIPTION` ingestion for Base64/plain SS, VMess, VLESS, Trojan,
 > Hysteria2, TUIC, and AnyTLS URI
 > lines and Mihomo/Clash provider YAML, which keeps the supported nodes of a
@@ -58,7 +58,7 @@ home directory all use the same name: `jerryproxy`.
 > credentials and `--bind-all` explicitly selects `0.0.0.0`. Native profiles,
 > other core drivers, and the historical `v2raycli` compatibility layer remain
 > planned. This is the first public release; the `0.x` API and state formats are
-> not stable yet. See the [release notes](https://github.com/narugo1992/jerryproxy/blob/main/RELEASE_NOTES.md) for the complete
+> not stable yet. See the [release notes](https://github.com/narugo1992/jerryproxy/releases/latest) for the complete
 > scope, verification evidence, and known limitations.
 
 ## Current status
@@ -130,7 +130,8 @@ Python.
 
 ## Installation
 
-The first public release is `0.1.0`. It is an alpha-quality `0.x` release, so
+The source tree is prepared for `0.2.0`; publication is pending. The first
+public release was `0.1.0`. This remains an alpha-quality `0.x` project, so
 the API and managed-state formats may change between releases. Install it from
 PyPI with:
 
@@ -379,7 +380,9 @@ backend registry, packaged catalog access and selection, `filelock`
 compatibility, and one lock-consistent installed/active backend inventory. It
 also exercises a complete synthetic backend lifecycle plus install, activation,
 and removal hard-exit recovery in isolated temporary JerryProxy homes without
-changing the configured home. It then streams one fixed 1 MiB Range from
+changing the configured home. A separate health-worker check spawns the actual
+network worker against a temporary loopback HTTP server, verifies the
+response and confirms cleanup without external traffic. It then streams one fixed 1 MiB Range from
 a pinned public Xray release through each built-in relay. The probe separates
 response-header latency, first-chunk latency, and the speed of the remaining
 chunks, uses a five-second connect/read timeout, and has a parent-enforced
@@ -486,6 +489,14 @@ prefers GitHub API digests, and reads official checksum text only for legacy
 assets where the API has no digest. It never downloads backend archives to
 calculate catalog fingerprints. The updater is not included in the wheel.
 
+Scheduled and manual runs first look for an open catalog review. New reviews
+use the exact title `chore(catalog): refresh backend release catalogs` and the
+body marker `<!-- jerryproxy:backend-catalog-refresh -->`; both must match.
+Existing legacy bot reviews are also recognized by title, author, and branch.
+When a review is open, the run comments on the newest matching PR and skips
+refreshing or publishing a branch. After that review is merged or closed, a
+later run may create a new review. Query failures stop the workflow.
+
 Relay-health monitoring is also repository infrastructure, not JerryProxy
 runtime behavior. Its 57-site configuration lives in a dedicated
 [Gist](https://gist.github.com/narugo1992/78fb0ee6135fcdf4f0e5c7ec38f2fd59).
@@ -540,10 +551,57 @@ SOCKS5 listener uses a `socks5h` URL. Backend stdout/stderr are merged into one
 bounded live stream, redacted, and labeled only with the backend name
 (`[mihomo]`), never separate stdout/stderr labels; `--backend-log-level`
 defaults to `INFO`. Two consecutive
-failed global health quorums trigger one same-node restart, deterministic
-alternate-node attempts, and one optional subscription refresh within the
-configured recovery deadline. Automatic recovery never rewrites the saved node
-preference.
+failed global health quorums trigger persistent recovery within the selected
+subscription. Health checks default to 30 seconds, with a confirmation check
+3 seconds after a failure. The backend stays running while nodes are retried
+and hot-reloaded; each recovery round has its own budget and capped backoff.
+Healthy sessions keep their node, listener and credentials, and automatic
+recovery never rewrites the saved preference. Temporary subscription transport
+failures retain verified cache, with separate refresh backoff and Retry-After
+handling. Cache older than 12 hours requests refresh without disqualifying its
+nodes. Control, TLS, authentication, integrity and unclassified failures remain
+terminal. Lifecycle events report starting, degradation, retry attempts,
+refresh outcomes, readiness and completed cleanup. JSONL sends events to stdout
+and ordinary logs to stderr; event visibility is independent of log level.
+Both log producers retain recent redacted diagnostics within a 4 MiB file.
+SIGINT and SIGTERM unwind the foreground session and exit with status 130
+and 143 after cleanup; repeated signals do not interrupt that cleanup. Default
+health requests run in a disposable process that is stopped at the wall deadline,
+so stalled network requests cannot occupy future probe batches. Unconfirmed
+worker cleanup is terminal and retains the home lock; recovery never hides an
+unsafe process state. Existing client connections are not guaranteed to survive
+a node change.
+
+Choose `--retry-policy none|fixed|random|adaptive|fallback` in a complete command
+or select the same policy in the guided TTY flow. The default `fallback` uses
+`current:1,adaptive:3,random:all`; `--retry-chain current:1,random:all` selects a
+custom fallback chain. Stages must be unique, counts must be positive integers
+(up to 10,000) or `all`, and `current` permits only `current:1`. Custom chains
+require `fallback`. `none` stops on confirmed failure and disables refresh;
+`fixed` never substitutes a different initial identity; `random` visits nodes
+without replacement; `adaptive` uses aging session-local successes with
+recovery-only exploration. Human and JSONL startup report the chosen policy.
+
+Defaults target subscriptions with up to 20 nodes. Recovery first uses short
+3-second health probes, then normal budgets after the fast sweep is exhausted
+so slow usable nodes remain eligible. After 6 seconds spent trying cached
+nodes, the next between-attempt check gives subscription refresh its own
+10-second budget; a large old pool cannot consume that fetch budget. Refresh
+starts at most once per 60 seconds by default, with additional transport
+backoff and Retry-After handling. Changed content is tried without an extra
+round backoff. An in-flight bounded attempt finishes before the refresh check;
+these timings are not a guarantee that an available route exists.
+
+Advanced overrides are `--fast-probe-timeout 3`, `--cache-retry-budget 6`,
+`--refresh-timeout 10` and `--refresh-interval 60` (all seconds). Complete
+commands and guided selection share these defaults and overrides. The guided
+flow adds no timing questions; choosing the recommended policy is sufficient.
+
+```shell
+jerryproxy server --subscription main --node NODE_ID --retry-policy fixed
+jerryproxy server --subscription main --node NODE_ID --retry-policy fallback \
+  --retry-chain current:1,adaptive:3,random:all
+```
 
 Nodes are listed with the label their provider put in the URI fragment, so
 several endpoints of one protocol stay distinguishable. That fragment is
@@ -627,7 +685,7 @@ tampering and is never repaired automatically.
 - [x] Implement managed `V2RAY_SUBSCRIPTION` fetch, private state, and URI
   inventory for every encrypted protocol the qualified backend accepts.
 - [x] Implement the Mihomo foreground driver, loopback listener, merged named
-  backend stream, and bounded health recovery.
+  backend stream, and persistent health recovery with bounded rounds.
 - [ ] Implement durable controller operations, measurements, and service
   integration.
 - [ ] Preserve documented `v2raycli` inputs through deprecated aliases.

{jerryproxy-0.1.0 → jerryproxy-0.2.0}/README.md

@@ -5,7 +5,7 @@ switching, and eventually orchestrating multiple external proxy backends. The
 PyPI distribution, Python import, GitHub repository, CLI command, and default
 home directory all use the same name: `jerryproxy`.
 
-> **0.1.0 alpha-quality release:** the first runtime slice is implemented: bounded
+> **0.2.0 release preparation (alpha quality):** the current runtime slice implements bounded
 > `V2RAY_SUBSCRIPTION` ingestion for Base64/plain SS, VMess, VLESS, Trojan,
 > Hysteria2, TUIC, and AnyTLS URI
 > lines and Mihomo/Clash provider YAML, which keeps the supported nodes of a
@@ -17,7 +17,7 @@ home directory all use the same name: `jerryproxy`.
 > credentials and `--bind-all` explicitly selects `0.0.0.0`. Native profiles,
 > other core drivers, and the historical `v2raycli` compatibility layer remain
 > planned. This is the first public release; the `0.x` API and state formats are
-> not stable yet. See the [release notes](https://github.com/narugo1992/jerryproxy/blob/main/RELEASE_NOTES.md) for the complete
+> not stable yet. See the [release notes](https://github.com/narugo1992/jerryproxy/releases/latest) for the complete
 > scope, verification evidence, and known limitations.
 
 ## Current status
@@ -89,7 +89,8 @@ Python.
 
 ## Installation
 
-The first public release is `0.1.0`. It is an alpha-quality `0.x` release, so
+The source tree is prepared for `0.2.0`; publication is pending. The first
+public release was `0.1.0`. This remains an alpha-quality `0.x` project, so
 the API and managed-state formats may change between releases. Install it from
 PyPI with:
 
@@ -338,7 +339,9 @@ backend registry, packaged catalog access and selection, `filelock`
 compatibility, and one lock-consistent installed/active backend inventory. It
 also exercises a complete synthetic backend lifecycle plus install, activation,
 and removal hard-exit recovery in isolated temporary JerryProxy homes without
-changing the configured home. It then streams one fixed 1 MiB Range from
+changing the configured home. A separate health-worker check spawns the actual
+network worker against a temporary loopback HTTP server, verifies the
+response and confirms cleanup without external traffic. It then streams one fixed 1 MiB Range from
 a pinned public Xray release through each built-in relay. The probe separates
 response-header latency, first-chunk latency, and the speed of the remaining
 chunks, uses a five-second connect/read timeout, and has a parent-enforced
@@ -445,6 +448,14 @@ prefers GitHub API digests, and reads official checksum text only for legacy
 assets where the API has no digest. It never downloads backend archives to
 calculate catalog fingerprints. The updater is not included in the wheel.
 
+Scheduled and manual runs first look for an open catalog review. New reviews
+use the exact title `chore(catalog): refresh backend release catalogs` and the
+body marker `<!-- jerryproxy:backend-catalog-refresh -->`; both must match.
+Existing legacy bot reviews are also recognized by title, author, and branch.
+When a review is open, the run comments on the newest matching PR and skips
+refreshing or publishing a branch. After that review is merged or closed, a
+later run may create a new review. Query failures stop the workflow.
+
 Relay-health monitoring is also repository infrastructure, not JerryProxy
 runtime behavior. Its 57-site configuration lives in a dedicated
 [Gist](https://gist.github.com/narugo1992/78fb0ee6135fcdf4f0e5c7ec38f2fd59).
@@ -499,10 +510,57 @@ SOCKS5 listener uses a `socks5h` URL. Backend stdout/stderr are merged into one
 bounded live stream, redacted, and labeled only with the backend name
 (`[mihomo]`), never separate stdout/stderr labels; `--backend-log-level`
 defaults to `INFO`. Two consecutive
-failed global health quorums trigger one same-node restart, deterministic
-alternate-node attempts, and one optional subscription refresh within the
-configured recovery deadline. Automatic recovery never rewrites the saved node
-preference.
+failed global health quorums trigger persistent recovery within the selected
+subscription. Health checks default to 30 seconds, with a confirmation check
+3 seconds after a failure. The backend stays running while nodes are retried
+and hot-reloaded; each recovery round has its own budget and capped backoff.
+Healthy sessions keep their node, listener and credentials, and automatic
+recovery never rewrites the saved preference. Temporary subscription transport
+failures retain verified cache, with separate refresh backoff and Retry-After
+handling. Cache older than 12 hours requests refresh without disqualifying its
+nodes. Control, TLS, authentication, integrity and unclassified failures remain
+terminal. Lifecycle events report starting, degradation, retry attempts,
+refresh outcomes, readiness and completed cleanup. JSONL sends events to stdout
+and ordinary logs to stderr; event visibility is independent of log level.
+Both log producers retain recent redacted diagnostics within a 4 MiB file.
+SIGINT and SIGTERM unwind the foreground session and exit with status 130
+and 143 after cleanup; repeated signals do not interrupt that cleanup. Default
+health requests run in a disposable process that is stopped at the wall deadline,
+so stalled network requests cannot occupy future probe batches. Unconfirmed
+worker cleanup is terminal and retains the home lock; recovery never hides an
+unsafe process state. Existing client connections are not guaranteed to survive
+a node change.
+
+Choose `--retry-policy none|fixed|random|adaptive|fallback` in a complete command
+or select the same policy in the guided TTY flow. The default `fallback` uses
+`current:1,adaptive:3,random:all`; `--retry-chain current:1,random:all` selects a
+custom fallback chain. Stages must be unique, counts must be positive integers
+(up to 10,000) or `all`, and `current` permits only `current:1`. Custom chains
+require `fallback`. `none` stops on confirmed failure and disables refresh;
+`fixed` never substitutes a different initial identity; `random` visits nodes
+without replacement; `adaptive` uses aging session-local successes with
+recovery-only exploration. Human and JSONL startup report the chosen policy.
+
+Defaults target subscriptions with up to 20 nodes. Recovery first uses short
+3-second health probes, then normal budgets after the fast sweep is exhausted
+so slow usable nodes remain eligible. After 6 seconds spent trying cached
+nodes, the next between-attempt check gives subscription refresh its own
+10-second budget; a large old pool cannot consume that fetch budget. Refresh
+starts at most once per 60 seconds by default, with additional transport
+backoff and Retry-After handling. Changed content is tried without an extra
+round backoff. An in-flight bounded attempt finishes before the refresh check;
+these timings are not a guarantee that an available route exists.
+
+Advanced overrides are `--fast-probe-timeout 3`, `--cache-retry-budget 6`,
+`--refresh-timeout 10` and `--refresh-interval 60` (all seconds). Complete
+commands and guided selection share these defaults and overrides. The guided
+flow adds no timing questions; choosing the recommended policy is sufficient.
+
+```shell
+jerryproxy server --subscription main --node NODE_ID --retry-policy fixed
+jerryproxy server --subscription main --node NODE_ID --retry-policy fallback \
+  --retry-chain current:1,adaptive:3,random:all
+```
 
 Nodes are listed with the label their provider put in the URI fragment, so
 several endpoints of one protocol stay distinguishable. That fragment is
@@ -586,7 +644,7 @@ tampering and is never repaired automatically.
 - [x] Implement managed `V2RAY_SUBSCRIPTION` fetch, private state, and URI
   inventory for every encrypted protocol the qualified backend accepts.
 - [x] Implement the Mihomo foreground driver, loopback listener, merged named
-  backend stream, and bounded health recovery.
+  backend stream, and persistent health recovery with bounded rounds.
 - [ ] Implement durable controller operations, measurements, and service
   integration.
 - [ ] Preserve documented `v2raycli` inputs through deprecated aliases.

{jerryproxy-0.1.0 → jerryproxy-0.2.0}/docs/source/api_doc/errors.rst

@@ -115,6 +115,13 @@ SubscriptionFetchError
 .. autoclass:: SubscriptionFetchError
 
 
+SubscriptionTransportError
+-----------------------------------------------------
+
+.. autoclass:: SubscriptionTransportError
+   :members: __init__
+
+
 SubscriptionParseError
 -----------------------------------------------------
 

jerryproxy-0.2.0/docs/source/api_doc/runtime/_logs.rst

@@ -0,0 +1,14 @@
+:orphan:
+
+jerryproxy.runtime.\_logs
+========================================================
+
+.. currentmodule:: jerryproxy.runtime._logs
+
+.. automodule:: jerryproxy.runtime._logs
+
+
+append\_recent
+-----------------------------------------------------
+
+.. autofunction:: append_recent

jerryproxy-0.2.0/docs/source/api_doc/runtime/_probe.rst

@@ -0,0 +1,15 @@
+:orphan:
+
+jerryproxy.runtime.\_probe
+========================================================
+
+.. currentmodule:: jerryproxy.runtime._probe
+
+.. automodule:: jerryproxy.runtime._probe
+
+
+ProbeProcess
+-----------------------------------------------------
+
+.. autoclass:: ProbeProcess
+   :members: __init__,close,check

{jerryproxy-0.1.0 → jerryproxy-0.2.0}/docs/source/api_doc/runtime/health.rst

@@ -45,14 +45,14 @@ ConnectivityProbe
 -----------------------------------------------------
 
 .. autoclass:: ConnectivityProbe
-   :members: __init__,check
+   :members: __init__,check,close
 
 
 RecoveryPolicy
 -----------------------------------------------------
 
 .. autoclass:: RecoveryPolicy
-   :members: health_interval,recovery_deadline,startup_retry_delays,same_node_delay,alternate_delays,refresh_on_failure,refresh_stale_seconds,failure_cooldown,__post_init__
+   :members: retry_policy,retry_chain,confirmation_delay,refresh_interval,fast_probe_timeout,cache_retry_budget,refresh_timeout,health_interval,recovery_deadline,refresh_on_failure,refresh_stale_seconds,__post_init__
 
 
 RecoveryDeadline

{jerryproxy-0.1.0 → jerryproxy-0.2.0}/docs/source/api_doc/runtime/index.rst

@@ -13,6 +13,7 @@ jerryproxy.runtime
    health
    interfaces
    mihomo
+   recovery
    session
 
 \_\_all\_\_

{jerryproxy-0.1.0 → jerryproxy-0.2.0}/docs/source/api_doc/runtime/interfaces.rst

@@ -17,11 +17,11 @@ LoadedNodes
 -----------------------------------------------------
 
 .. autoclass:: LoadedNodes
-   :members: accepted,selected,bypassing
+   :members: accepted,selected,bypassing,identities
 
 
 RuntimeDriver
 -----------------------------------------------------
 
 .. autoclass:: RuntimeDriver
-   :members: name,projection,loaded_nodes,create_process,wait_ready,stop
+   :members: name,projection,loaded_nodes,reload_provider,create_process,wait_ready,stop

{jerryproxy-0.1.0 → jerryproxy-0.2.0}/docs/source/api_doc/runtime/mihomo.rst

@@ -52,7 +52,7 @@ MihomoDriver
 -----------------------------------------------------
 
 .. autoclass:: MihomoDriver
-   :members: __init__,name,projection,loaded_nodes,create_process,wait_ready,stop
+   :members: __init__,name,projection,loaded_nodes,reload_provider,create_process,wait_ready,stop
 
 
 MihomoProcess

jerryproxy-0.2.0/docs/source/api_doc/runtime/recovery.rst

@@ -0,0 +1,40 @@
+jerryproxy.runtime.recovery
+========================================================
+
+.. currentmodule:: jerryproxy.runtime.recovery
+
+.. automodule:: jerryproxy.runtime.recovery
+
+
+DEFAULT\_RETRY\_CHAIN
+-----------------------------------------------------
+
+.. autodata:: DEFAULT_RETRY_CHAIN
+   :no-value:
+
+
+RETRY\_POLICIES
+-----------------------------------------------------
+
+.. autodata:: RETRY_POLICIES
+   :no-value:
+
+
+RetrySchedule
+-----------------------------------------------------
+
+.. autoclass:: RetrySchedule
+   :members: __init__,begin_sweep,update,record,wait_seconds,next
+
+
+RetryBackoff
+-----------------------------------------------------
+
+.. autoclass:: RetryBackoff
+   :members: __init__,healthy,failed
+
+
+parse\_retry\_chain
+-----------------------------------------------------
+
+.. autofunction:: parse_retry_chain

{jerryproxy-0.1.0 → jerryproxy-0.2.0}/docs/source/index.rst

@@ -5,7 +5,7 @@ JerryProxy is a Python 3.7+ multi-backend proxy CLI and backend manager.
 
 .. warning::
 
-   JerryProxy 0.1.0 is the first public, alpha-quality release. The current
+   JerryProxy 0.2.0 is prepared for release; publication is pending. The current
    runtime slice accepts bounded ``V2RAY_SUBSCRIPTION`` URI sources and
    Mihomo/Clash proxy-provider YAML for the encrypted protocols the qualified
    backend accepts, and runs Mihomo 1.19.29 in the foreground. Native profiles,
@@ -21,4 +21,5 @@ JerryProxy is a Python 3.7+ multi-backend proxy CLI and backend manager.
    architecture
    security
    roadmap
+   runtime_recovery
    api_doc

{jerryproxy-0.1.0 → jerryproxy-0.2.0}/docs/source/installation.rst

@@ -1,7 +1,7 @@
 Installation
 ============
 
-JerryProxy 0.1.0 is the first public, alpha-quality release. It supports Python
+JerryProxy 0.2.0 is prepared for release; publication is pending. It supports Python
 3.7 and newer and is distributed as a pure-Python wheel. The ``0.x`` API and
 managed-state formats are not stable yet.
 

jerryproxy-0.2.0/docs/source/runtime_recovery.rst

@@ -0,0 +1,220 @@
+Persistent recovery implementation contract
+===========================================
+
+This contract defines persistent recovery and its merge acceptance criteria.
+It implements the maintainer's
+Chinese design document, revision 8, dated 2026-09-21.
+
+Inputs and boundaries
+---------------------
+
+The caller explicitly selects one subscription and one initial node. Recovery
+must never leave that subscription, change its saved preference, interpret
+protocol credentials, or replace the existing runtime-driver boundary.
+Healthy sessions keep their current node; exploration and exit-IP changes
+are permitted only during recovery. There is no automatic failback.
+
+Startup and periodic outages use the same recovery path. Transient outages
+have no session lifetime limit. Each probe, reload, refresh, cleanup and retry
+round remains bounded. A round deadline preserves pending candidates rather
+than repeatedly starving the tail of a large subscription.
+
+Fast recovery defaults
+----------------------
+
+For subscriptions with up to 20 nodes, the first recovery sweep uses a
+three-second health budget per candidate. After six seconds on cached
+candidates, the next between-attempt check gives a source refresh an
+independent ten-second budget. An in-flight bounded reload/probe completes
+before this check; six seconds is a scheduling threshold, not a hard wall.
+Refresh is checked between attempts and rounds, never only against the
+remaining round budget. Its default minimum interval is 60 seconds, with
+transport backoff and Retry-After still enforced. Changed source content is
+eligible immediately without an extra round backoff. An exhausted fast sweep
+falls back to normal probe budgets so slow usable nodes are not excluded.
+Healthy sessions retain the existing check interval and never explore.
+
+These defaults target fast restoration rather than an optimal-node search.
+Verification compares 1, 5, 10 and 20-node replacement and partial-outage
+scenarios, including slow usable nodes, unchanged/failed refresh, deadline
+exhaustion and CLI/guided default and override parity. Simulated timing is
+not a public-network latency guarantee. Safety and cleanup remain terminal
+boundaries. Advanced timing options must not add guided questions.
+
+``--fast-probe-timeout`` (3), ``--cache-retry-budget`` (6),
+``--refresh-timeout`` (10) and ``--refresh-interval`` (60) are advanced
+overrides in seconds. Both complete commands and guided selection use these
+defaults without extra prompts. An unchanged or temporarily unavailable
+subscription keeps the existing pool and bounded retry cadence. A recent
+refresh can defer the next fetch; server Retry-After can defer it further.
+These are not restoration-time guarantees.
+
+Default selection evidence
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A deterministic comparison used the real session scheduler/private provider
+publication with injected network time: 1/5/10/20 nodes, five ordering seeds,
+one working node, two-second fetches, and 1/3/5/8-second successful probes.
+The reference replayed the recovery loop at ``7f40af8`` with its 300-second
+refresh interval. Controller and process latency were not simulated; results
+start at confirmed recovery, excluding failure detection.
+
+For complete replacement with a one-second working node, the 3-second default
+reduced sample P95 from 405 to 42 simulated seconds (maximum 54). For partial
+failure with a three-second working node, sample P95 was 35 seconds, versus
+223 with a two-second fast budget and 55 with a five-second fast budget.
+Three seconds is the smallest compared budget that accepts this moderately
+slow route on the first sweep. It is a workload choice, not a universal optimum.
+For five-second working nodes the fast sweep adds work: sample P95 was 245
+seconds versus 105 in the reference. Normal-budget retries preserve recovery
+in this case; users of consistently slow routes can increase the fast budget.
+
+``test/runtime/test_fast_recovery.py`` pins the default first-sweep bound for
+1--20 nodes with 1/3-second successful probes over five seeds, prompt complete
+replacement, independent refresh even at round exhaustion, throttling and
+normal-budget fallback. These model checks supplement the real protocol
+data-plane suite; they do not replace it or imply public-network percentiles.
+
+Selection policies
+------------------
+
+* ``none`` stops after confirmed failure without restarting or refreshing.
+* ``fixed`` retries only the initial node identity.
+* ``random`` visits a shuffled pool without replacement before another sweep.
+* ``adaptive`` uses session-local, aging success estimates and recovery-only
+  exploration; all eligible nodes must eventually receive an attempt.
+* ``fallback`` composes the closed stages ``current``, ``adaptive`` and
+  ``random``. The default is ``current:1,adaptive:3,random:all``. Stage names
+  must be unique; counts are positive bounded integers or ``all``. Current
+  permits only one attempt. Candidates are deduplicated across stages.
+
+Retry timing uses capped exponential backoff with jitter, separate node
+cooldowns and refresh throttling. A brief success does not reset escalation;
+only a stable healthy period does. No tight loop is allowed for exhausted,
+unchanged, disabled or cooling-down pools.
+
+Execution and outputs
+---------------------
+
+The session keeps its home-wide lock, listener port and optional credentials
+through degradation. Mihomo uses atomic private single-provider publication
+and authenticated bounded reloads. Exact candidate acceptance, selection and
+absence of direct bypass must be checked before connectivity can establish
+readiness. Each control request has an absolute wall deadline covering response
+headers and body, including slow trickles. A standard-library buffered reader
+clamps each underlying socket read to the remaining time; no deadline worker
+is allocated. Ambiguous control state, authentication, integrity, TLS, permission
+and unsafe cleanup failures remain terminal. Health probes report certificate
+validation failure and explicit HTTP 407 responses as closed terminal
+verdicts, never as ordinary target outages. CONNECT 407 refusals are recognized
+only through the pinned Requests/urllib3/standard-library exception chain and
+the locally generated status prefix; arbitrary exception messages are never
+searched or logged. Other proxy connection failures remain retryable. A real
+loopback proxy refusal verifies classification across the health process
+boundary. Confirmed child exit must not be confused with inability to stop a child.
+
+Cache age requests a refresh but does not disqualify verified cached nodes.
+Temporary refresh failure preserves the last good revision. Successful refresh
+prunes removed identities and statistics; removing the fixed identity produces
+an actionable error. Recovery refresh receives an independent budget and respects its
+own minimum interval, backoff and server Retry-After. Retry-After is bounded
+to one day; malformed values are discarded. Refresh starts no more often than
+once per 60 seconds by default, doubles its delay after consecutive transport
+failures up to one hour, and resets after success. Mandatory worker cleanup has
+separate bounded stop intervals and must complete even after the network
+budget expires; inability to prove cleanup is terminal. A standalone
+subscription operation retains its original home lock while cleanup remains
+unconfirmed. The same manager, used on its owning thread, may release that
+retained lock on its next operation only after the supervisor confirms both worker termination and
+artifact removal. A runtime session similarly refuses to announce stopped
+or release its own lock while subscription cleanup is pending. No cleanup
+thread releases a thread-owned FileLock or acquires a second home lock.
+The subscription caller waits on a starter-owned completion event rather than
+an interruptible thread join, which can incorrectly report a live starter as
+stopped on older CPython versions. The cleanup supervisor also confirms actual
+starter exit before removing the private worker directory.
+Acquired operation locks remain strongly referenced until explicit exit, so
+discarding a failed owner cannot release an unconfirmed operation through
+garbage collection. Discarding such an owner forfeits in-process cleanup
+recovery; the home stays locked until the process exits.
+
+Sanitized events expose starting, degraded, retrying, ready and stopped states,
+actual retry delays, skip reasons and current health. No event falsely reports
+readiness or exposes secrets. Threads, children, statistics and recent logs
+remain bounded for an indefinitely running session. Ctrl-C and SIGTERM must
+cancel probes, refreshes and backoff and complete safe cleanup. The CLI owns
+SIGINT and SIGTERM handlers only during the foreground session. The first
+signal requests unwinding; repeated signals are ignored until cleanup has
+finished, then prior handlers are restored. Successful cancellation exits
+with 128 plus the signal number. Cleanup failure remains a terminal error.
+
+Lifecycle events use a separate optional event callback. JSONL emits these
+events on stdout and ordinary logs on stderr, independent of log-level
+filtering. The session writes the same bounded event summary to its private
+log. Each event includes a closed reason code, attempt and round counters,
+candidate count, last healthy effective node, loaded node, attempted node,
+current quorum and actual next delay. Startup emits ready only after access
+publication; recovery emits ready only after acceptance and quorum. Stopped
+is emitted only after child and artifact cleanup succeeds, while the home
+lock still protects the event log write. Refresh events preserve the current
+state and distinguish stale cache, unchanged content, updated content and
+transient transport failure. Repeated stop is
+idempotent. A closed output stream does not interrupt service.
+
+Default network checks run in one disposable spawned process with at most
+three request threads. The parent includes process startup in the check
+budget, terminates the process on timeout or interruption, and confirms exit
+before accepting another batch. Credentials travel through multiprocessing
+IPC rather than command arguments or files. Results use a bounded, validated
+JSON envelope with closed diagnostic codes. Cleanup retains a separate bounded
+budget and fails closed on uncertain process ownership. Injected transports
+run in-process for deterministic testing. Library scripts that launch default
+probes must use the standard ``if __name__ == "__main__"`` entry guard
+required by multiprocessing spawn; the CLI already provides that guard.
+The installed ``self-check`` exercises the actual spawned health worker against
+a temporary loopback HTTP server. It requires a successful round trip and
+confirmed cleanup; standalone artifact CI runs this check on each target OS.
+
+Injected in-process checks allocate at most three workers. If a request outlives
+a check's budget, subsequent checks report it as unfinished and allocate no new
+workers until that batch finishes. Late results do not establish readiness for
+a later check. Cancellation prevents pending targets from starting. Completion
+is tracked with worker-owned events instead of interruptible joins; cleanup
+must confirm all workers have exited before releasing the home lock. An
+unconfirmed worker makes cleanup fail closed. This bounds worker accumulation but does not by itself prove
+that an arbitrary injected transport can be cancelled. Default network
+transports instead use the disposable process described above. Native platform
+and packaged-executable verification run in the repository CI matrix.
+
+Runtime logs retain recent diagnostics within a 4 MiB file. Both producers
+serialize writes under the existing shared lock. Descriptors use binary mode
+on Windows so byte bounds and compaction offsets are not changed by newline
+translation. On overflow they discard
+the oldest portion, retain complete recent lines from the final half and
+append the new redacted line through the same validated descriptor. No
+rotation paths are created. A crash during this in-place compaction can lose
+diagnostic history; it cannot modify managed configuration or credentials.
+
+Verification required before merge
+----------------------------------
+
+Tests are written before behavior. Deterministic scenarios cover startup
+offline then online, outages longer than 120 seconds, all nodes unavailable,
+one working alternate, subscription scope, fixed identity, no healthy
+switching, hundreds of candidates, cooldowns, unchanged and failing refresh,
+old usable cache, removed fixed identity, flapping and cancellation at each
+blocking boundary. Adversarial reload tests cover empty and malicious
+providers, stale accepted content, authorization and rollback failures.
+
+Real qualified-backend data-plane tests cover every allowed protocol and
+container, including hot switches with stable listener and credentials.
+Long-run tests verify bounded workers, logs and statistics. Existing secret
+matrices must include new output channels. Explicit and guided CLI behavior
+must agree; rendered help is checked at 72, 80, 100 and 120 columns.
+
+All changed or affected functions require 100 percent branch coverage,
+including native platform evidence when necessary, without exclusion pragmas
+or a whole-repository average substituting for the affected-area audit.
+Python 3.7 compatibility, normal test gates, generated API documentation,
+documentation build and package build must pass. The PR body is English;
+completion requires review and CI evidence that the full scope is merge-ready.