Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

128 KB
Raw Blame
diff --git a/cmd/server/local_management_password.go b/cmd/server/local_management_password.go
new file mode 100644
index 0000000..67333ea
--- /dev/null
+++ b/cmd/server/local_management_password.go
@@ -0,0 +1,24 @@
+package main
+
+import (
+	"errors"
+	"io"
+)
+
+// The managed parent owns this pipe and closes it after one bounded random credential.
+// Keep credentials out of argv, environment variables and diagnostic messages.
+func readLocalManagementPassword(input io.Reader) (string, error) {
+	content, errRead := io.ReadAll(io.LimitReader(input, 129))
+	if errRead != nil || len(content) < 32 || len(content) > 128 {
+		return "", errors.New("invalid local management credential")
+	}
+	for _, c := range content {
+		if !((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') ||
+			(c >= '0' && c <= '9') || c == '-' || c == '_') {
+			return "", errors.New("invalid local management credential")
+		}
+	}
+	password := string(content)
+	clear(content)
+	return password, nil
+}
diff --git a/cmd/server/local_management_password_test.go b/cmd/server/local_management_password_test.go
new file mode 100644
index 0000000..abb036f
--- /dev/null
+++ b/cmd/server/local_management_password_test.go
@@ -0,0 +1,19 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestLocalManagementPasswordPipeBounds(t *testing.T) {
+	for _, invalid := range []string{"", strings.Repeat("x", 31), strings.Repeat("x", 129), strings.Repeat("x", 32) + "\n", strings.Repeat("x", 32) + "\x00"} {
+		if value, errRead := readLocalManagementPassword(strings.NewReader(invalid)); errRead == nil || value != "" {
+			t.Fatal("invalid credential was accepted")
+		}
+	}
+	for _, valid := range []string{strings.Repeat("x", 32), strings.Repeat("x", 128), strings.Repeat("a-B_", 10)} {
+		if value, errRead := readLocalManagementPassword(strings.NewReader(valid)); errRead != nil || value != valid {
+			t.Fatal("valid credential was rejected")
+		}
+	}
+}
diff --git a/cmd/server/main.go b/cmd/server/main.go
index 2b99077..a661fbb 100644
--- a/cmd/server/main.go
+++ b/cmd/server/main.go
@@ -125,6 +125,7 @@ func main() {
 	var vertexImportPrefix string
 	var configPath string
 	var password string
+	var localPasswordStdin bool
 	var homeJWT string
 	var homeDisableClusterDiscovery bool
 	var tuiMode bool
@@ -154,6 +155,7 @@ func main() {
 	flag.StringVar(&vertexImport, "vertex-import", "", "Import Vertex service account key JSON file")
 	flag.StringVar(&vertexImportPrefix, "vertex-import-prefix", "", "Prefix for Vertex model namespacing (use with -vertex-import)")
 	flag.StringVar(&password, "password", "", "")
+	flag.BoolVar(&localPasswordStdin, "local-password-stdin", false, "Read the local management credential from the parent pipe")
 	flag.StringVar(&homeJWT, "home-jwt", "", "Home control plane JWT for mTLS certificate bootstrap and connection")
 	flag.BoolVar(&homeDisableClusterDiscovery, "home-disable-cluster-discovery", false, "Disable Home CLUSTER NODES discovery and keep using the configured -home-jwt address")
 	flag.BoolVar(&tuiMode, "tui", false, "Start with terminal management UI")
@@ -198,6 +200,18 @@ func main() {
 
 	// Parse the command-line flags.
 	flag.Parse()
+	if localPasswordStdin {
+		if password != "" || os.Getenv("MANAGEMENT_PASSWORD") != "" {
+			log.Error("local management pipe cannot be combined with another password input")
+			return
+		}
+		localPassword, errPassword := readLocalManagementPassword(os.Stdin)
+		if errPassword != nil {
+			log.Error("local management pipe credential is invalid")
+			return
+		}
+		password = localPassword
+	}
 
 	if discoverGateways || discoverJSON {
 		cfgInclude, cfgExclude := cmd.LoadDiscoveryScanFilters(configPath)
@@ -825,6 +839,11 @@ func main() {
 			managementasset.StartAutoUpdater(context.Background(), configFilePath)
 			misc.StartAntigravityVersionUpdater(context.Background())
 			startModelCatalogUpdaters(localModel, cfg.Home.Enabled)
+			if localPasswordStdin {
+				// The managed parent owns process lifetime, not the interactive keep-alive endpoint.
+				serverOptions = append(serverOptions, api.WithLocalManagementPassword(password))
+				password = ""
+			}
 			cmd.StartServiceWithPluginHost(cfg, configFilePath, password, pluginHost, serverOptions...)
 		}
 	}
diff --git a/internal/api/handlers/management/auth_files.go b/internal/api/handlers/management/auth_files.go
index 0a4ed74..5678a80 100644
--- a/internal/api/handlers/management/auth_files.go
+++ b/internal/api/handlers/management/auth_files.go
@@ -16,6 +16,7 @@ import (
 	"github.com/router-for-me/CLIProxyAPI/v8/internal/auth/codex"
 	"github.com/router-for-me/CLIProxyAPI/v8/internal/config"
 	"github.com/router-for-me/CLIProxyAPI/v8/internal/credentialweight"
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
 	"github.com/router-for-me/CLIProxyAPI/v8/internal/registry"
 	coreauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
 	log "github.com/sirupsen/logrus"
@@ -355,7 +356,10 @@ func (h *Handler) GetAuthFileModels(c *gin.Context) {
 
 	// Get models from registry
 	reg := registry.GetGlobalRegistry()
-	models := reg.GetModelsForClient(authID)
+	var models []*registry.ModelInfo
+	discovery := modeldiscovery.ReadCatalog(authID, func() {
+		models = reg.GetModelsForClient(authID)
+	})
 
 	result := make([]gin.H, 0, len(models))
 	for _, m := range models {
@@ -374,7 +378,7 @@ func (h *Handler) GetAuthFileModels(c *gin.Context) {
 		result = append(result, entry)
 	}
 
-	c.JSON(200, gin.H{"models": result})
+	c.JSON(200, gin.H{"models": result, "hiroute_model_discovery": discovery})
 }
 
 // List auth files from disk when the auth manager is unavailable.
diff --git a/internal/api/handlers/management/auth_files_discovery_test.go b/internal/api/handlers/management/auth_files_discovery_test.go
new file mode 100644
index 0000000..b4b2fb3
--- /dev/null
+++ b/internal/api/handlers/management/auth_files_discovery_test.go
@@ -0,0 +1,47 @@
+package management
+
+import (
+	"context"
+	"encoding/json"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/config"
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
+	coreauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
+)
+
+func TestHiRouteDiscoveryExistingManagementResponseResolvesFileName(t *testing.T) {
+	manager := coreauth.NewManager(nil, nil, nil)
+	a := &coreauth.Auth{ID: "private/internal/account", FileName: "private-file.json", Provider: "codex"}
+	if _, err := manager.Register(context.Background(), a); err != nil {
+		t.Fatal(err)
+	}
+	trace := modeldiscovery.Begin(a.ID)
+	trace.Enter(modeldiscovery.ClientVersion)
+	trace.End(modeldiscovery.Failed, modeldiscovery.ClientVersionUnavailable)
+	done := modeldiscovery.Registering(a.ID)
+	defer done()
+	handler := NewHandlerWithoutConfigFilePath(&config.Config{}, manager)
+	recorder := httptest.NewRecorder()
+	ctx, _ := gin.CreateTestContext(recorder)
+	ctx.Request = httptest.NewRequest("GET", "/v0/management/auth-files/models?name=private-file.json", nil)
+	handler.GetAuthFileModels(ctx)
+	var response struct {
+		Models    []any                   `json:"models"`
+		Discovery modeldiscovery.Snapshot `json:"hiroute_model_discovery"`
+	}
+	if err := json.Unmarshal(recorder.Body.Bytes(), &response); err != nil {
+		t.Fatal(err)
+	}
+	if recorder.Code != 200 || response.Models == nil || !response.Discovery.RegistrationPending || response.Discovery.FirstFailure == nil || response.Discovery.FirstFailure.Reason != modeldiscovery.ClientVersionUnavailable {
+		t.Fatalf("missing observation: %+v", response)
+	}
+	for _, private := range []string{a.ID, a.FileName, "access_token"} {
+		if strings.Contains(recorder.Body.String(), private) {
+			t.Fatal("private diagnostic material")
+		}
+	}
+}
diff --git a/internal/api/handlers/management/auth_files_oauth_callback.go b/internal/api/handlers/management/auth_files_oauth_callback.go
index f33f82e..3d87ba9 100644
--- a/internal/api/handlers/management/auth_files_oauth_callback.go
+++ b/internal/api/handlers/management/auth_files_oauth_callback.go
@@ -8,6 +8,7 @@ import (
 	"net/http"
 	"net/url"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/gin-gonic/gin"
@@ -39,23 +40,6 @@ func isWebUIRequest(c *gin.Context) bool {
 }
 
 func startCallbackForwarder(port int, provider, targetBase string) (*callbackForwarder, error) {
-	callbackForwardersMu.Lock()
-	prev := callbackForwarders[port]
-	if prev != nil {
-		delete(callbackForwarders, port)
-	}
-	callbackForwardersMu.Unlock()
-
-	if prev != nil {
-		stopForwarderInstance(port, prev)
-	}
-
-	addr := fmt.Sprintf("0.0.0.0:%d", port)
-	ln, err := net.Listen("tcp", addr)
-	if err != nil {
-		return nil, fmt.Errorf("failed to listen on %s: %w", addr, err)
-	}
-
 	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		target := targetBase
 		if raw := r.URL.RawQuery; raw != "" {
@@ -69,6 +53,24 @@ func startCallbackForwarder(port int, provider, targetBase string) (*callbackFor
 		http.Redirect(w, r, target, http.StatusFound)
 	})
 
+	return startCallbackServer(port, provider, handler)
+}
+
+func startCallbackServer(port int, provider string, handler http.Handler) (*callbackForwarder, error) {
+	callbackForwardersMu.Lock()
+	prev := callbackForwarders[port]
+	if prev != nil {
+		delete(callbackForwarders, port)
+	}
+	callbackForwardersMu.Unlock()
+	if prev != nil {
+		stopForwarderInstance(port, prev)
+	}
+	listeners, err := listenHiRouteCallbackLoopback(port)
+	if err != nil {
+		return nil, err
+	}
+
 	srv := &http.Server{
 		Handler:           handler,
 		ReadHeaderTimeout: 5 * time.Second,
@@ -76,10 +78,18 @@ func startCallbackForwarder(port int, provider, targetBase string) (*callbackFor
 	}
 	done := make(chan struct{})
 
+	var serving sync.WaitGroup
+	for _, listener := range listeners {
+		serving.Add(1)
+		go func(ln net.Listener) {
+			defer serving.Done()
+			if errServe := srv.Serve(ln); errServe != nil && !errors.Is(errServe, http.ErrServerClosed) {
+				log.Warn("local OAuth callback listener stopped unexpectedly")
+			}
+		}(listener)
+	}
 	go func() {
-		if errServe := srv.Serve(ln); errServe != nil && !errors.Is(errServe, http.ErrServerClosed) {
-			log.WithError(errServe).Warnf("callback forwarder for %s stopped unexpectedly", provider)
-		}
+		serving.Wait()
 		close(done)
 	}()
 
@@ -93,7 +103,7 @@ func startCallbackForwarder(port int, provider, targetBase string) (*callbackFor
 	callbackForwarders[port] = forwarder
 	callbackForwardersMu.Unlock()
 
-	log.Infof("callback forwarder for %s listening on %s", provider, addr)
+	log.Infof("callback listener for %s is ready on loopback port %d", provider, port)
 
 	return forwarder, nil
 }
diff --git a/internal/api/handlers/management/auth_files_provider_oauth.go b/internal/api/handlers/management/auth_files_provider_oauth.go
index 48fc4ef..ebacfa4 100644
--- a/internal/api/handlers/management/auth_files_provider_oauth.go
+++ b/internal/api/handlers/management/auth_files_provider_oauth.go
@@ -70,19 +70,17 @@ func (h *Handler) RequestAnthropicToken(c *gin.Context) {
 	RegisterOAuthSession(state, "anthropic")
 
 	isWebUI := isWebUIRequest(c)
+	callbackMode := "manual"
 	var forwarder *callbackForwarder
 	if isWebUI {
-		targetURL, errTarget := h.managementCallbackURL("/anthropic/callback")
-		if errTarget != nil {
-			log.WithError(errTarget).Error("failed to compute anthropic callback target")
-			c.JSON(http.StatusInternalServerError, gin.H{"error": "callback server unavailable"})
-			return
-		}
 		var errStart error
-		if forwarder, errStart = startCallbackForwarder(anthropicCallbackPort, "anthropic", targetURL); errStart != nil {
-			log.WithError(errStart).Error("failed to start anthropic callback forwarder")
-			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to start callback server"})
-			return
+		forwarder, errStart = startHiRouteCallbackReceiver(anthropicCallbackPort, "anthropic", state, h.cfg.AuthDir)
+		if errStart == nil {
+			callbackMode = "automatic"
+		} else {
+			// Keep this exact session for protected manual input. Do not disclose
+			// host errors or replace an unrelated process owning the callback port.
+			log.Warn("local OAuth callback listener unavailable; manual completion required")
 		}
 	}
 
@@ -142,6 +140,8 @@ func (h *Handler) RequestAnthropicToken(c *gin.Context) {
 		rawCode := resultMap["code"]
 		code := strings.Split(rawCode, "#")[0]
 
+		stopCallbackForwarderInstance(anthropicCallbackPort, forwarder)
+
 		// Exchange code for tokens using internal auth service
 		bundle, errExchange := anthropicAuth.ExchangeCodeForTokens(ctx, code, state, pkceCodes)
 		if errExchange != nil {
@@ -192,7 +192,7 @@ func (h *Handler) RequestAnthropicToken(c *gin.Context) {
 		CompleteOAuthSession(state)
 	}()
 
-	c.JSON(200, gin.H{"status": "ok", "url": authURL, "state": state})
+	c.JSON(200, gin.H{"status": "ok", "url": authURL, "state": state, "hiroute_callback_mode": callbackMode})
 }
 
 func (h *Handler) RequestCodexToken(c *gin.Context) {
@@ -231,19 +231,17 @@ func (h *Handler) RequestCodexToken(c *gin.Context) {
 	RegisterOAuthSession(state, "codex")
 
 	isWebUI := isWebUIRequest(c)
+	callbackMode := "manual"
 	var forwarder *callbackForwarder
 	if isWebUI {
-		targetURL, errTarget := h.managementCallbackURL("/codex/callback")
-		if errTarget != nil {
-			log.WithError(errTarget).Error("failed to compute codex callback target")
-			c.JSON(http.StatusInternalServerError, gin.H{"error": "callback server unavailable"})
-			return
-		}
 		var errStart error
-		if forwarder, errStart = startCallbackForwarder(codexCallbackPort, "codex", targetURL); errStart != nil {
-			log.WithError(errStart).Error("failed to start codex callback forwarder")
-			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to start callback server"})
-			return
+		forwarder, errStart = startHiRouteCallbackReceiver(codexCallbackPort, "codex", state, h.cfg.AuthDir)
+		if errStart == nil {
+			callbackMode = "automatic"
+		} else {
+			// Keep this exact session for protected manual input. Do not disclose
+			// host errors or replace an unrelated process owning the callback port.
+			log.Warn("local OAuth callback listener unavailable; manual completion required")
 		}
 	}
 
@@ -288,6 +286,7 @@ func (h *Handler) RequestCodexToken(c *gin.Context) {
 			time.Sleep(500 * time.Millisecond)
 		}
 
+		stopCallbackForwarderInstance(codexCallbackPort, forwarder)
 		log.Debug("Authorization code received, exchanging for tokens...")
 		// Exchange code for tokens using internal auth service
 		bundle, errExchange := openaiAuth.ExchangeCodeForTokens(ctx, code, pkceCodes)
@@ -353,7 +352,7 @@ func (h *Handler) RequestCodexToken(c *gin.Context) {
 		CompleteOAuthSession(state)
 	}()
 
-	c.JSON(200, gin.H{"status": "ok", "url": authURL, "state": state})
+	c.JSON(200, gin.H{"status": "ok", "url": authURL, "state": state, "hiroute_callback_mode": callbackMode})
 }
 
 func (h *Handler) RequestAntigravityToken(c *gin.Context) {
diff --git a/internal/api/handlers/management/hiroute_oauth_callback.go b/internal/api/handlers/management/hiroute_oauth_callback.go
new file mode 100644
index 0000000..7aac5b4
--- /dev/null
+++ b/internal/api/handlers/management/hiroute_oauth_callback.go
@@ -0,0 +1,107 @@
+package management
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+	"syscall"
+
+	"github.com/gin-gonic/gin"
+)
+
+// The registered localhost redirect can resolve to either family. Never fall
+// back to another interface or retain half a listener when the other is occupied.
+func listenHiRouteCallbackLoopback(port int) ([]net.Listener, error) {
+	var listeners []net.Listener
+	for _, address := range []struct{ network, host string }{{"tcp4", "127.0.0.1"}, {"tcp6", "::1"}} {
+		listener, err := net.Listen(address.network, net.JoinHostPort(address.host, strconv.Itoa(port)))
+		if err != nil {
+			if errors.Is(err, syscall.EAFNOSUPPORT) || errors.Is(err, syscall.EPROTONOSUPPORT) || errors.Is(err, syscall.EADDRNOTAVAIL) {
+				continue
+			}
+			for _, opened := range listeners {
+				_ = opened.Close()
+			}
+			return nil, fmt.Errorf("callback loopback unavailable: %w", err)
+		}
+		listeners = append(listeners, listener)
+	}
+	if len(listeners) == 0 {
+		return nil, errors.New("callback loopback unavailable")
+	}
+	return listeners, nil
+}
+
+func startHiRouteCallbackReceiver(port int, provider, state, authDir string) (*callbackForwarder, error) {
+	return startCallbackServer(port, provider, hiRouteCallbackHandler(port, provider, state, authDir))
+}
+
+func hiRouteCallbackHandler(port int, provider, state, authDir string) http.Handler {
+	path := "/auth/callback"
+	if provider == "anthropic" {
+		path = "/callback"
+	}
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Cache-Control", "no-store")
+		w.Header().Set("Referrer-Policy", "no-referrer")
+		w.Header().Set("Content-Security-Policy", "default-src 'none'; frame-ancestors 'none'")
+		w.Header().Set("X-Content-Type-Options", "nosniff")
+		host, requestPort, err := net.SplitHostPort(r.Host)
+		if err != nil || requestPort != strconv.Itoa(port) || (host != "localhost" && host != "127.0.0.1" && host != "::1") {
+			http.Error(w, "Invalid callback address.", http.StatusBadRequest)
+			return
+		}
+		if r.Method != http.MethodGet || r.URL.Path != path || r.URL.RawPath != "" || len(r.RequestURI) > 16384 {
+			http.Error(w, "Invalid callback request.", http.StatusBadRequest)
+			return
+		}
+		receiveHiRouteBrowserCallback(w, r, provider, state, authDir)
+	})
+}
+
+// The main-server callback paths share the same checked reception and never
+// claim login success just because a browser reached the endpoint.
+func HiRouteBrowserOAuthCallback(authDir, provider string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		c.Header("Cache-Control", "no-store")
+		c.Header("Referrer-Policy", "no-referrer")
+		c.Header("Content-Security-Policy", "default-src 'none'; frame-ancestors 'none'")
+		c.Header("X-Content-Type-Options", "nosniff")
+		receiveHiRouteBrowserCallback(c.Writer, c.Request, provider, "", authDir)
+	}
+}
+
+func receiveHiRouteBrowserCallback(w http.ResponseWriter, r *http.Request, provider, expectedState, authDir string) {
+	if len(r.RequestURI) > 16384 {
+		http.Error(w, "Invalid callback request.", http.StatusBadRequest)
+		return
+	}
+	query, err := url.ParseQuery(r.URL.RawQuery)
+	if err != nil || len(query["state"]) != 1 || query.Get("state") == "" || (expectedState != "" && query.Get("state") != expectedState) || len(query["code"]) > 1 || len(query["error"]) > 1 {
+		http.Error(w, "Invalid callback. Return to HiRoute to continue signing in.", http.StatusBadRequest)
+		return
+	}
+	code, oauthError := query.Get("code"), query.Get("error")
+	if (code == "") == (oauthError == "") || strings.ContainsAny(code+oauthError, "\r\n\x00") {
+		http.Error(w, "Invalid callback. Return to HiRoute to continue signing in.", http.StatusBadRequest)
+		return
+	}
+	if _, err := WriteOAuthCallbackFileForPendingSession(authDir, provider, query.Get("state"), code, oauthError); err != nil {
+		status := http.StatusInternalServerError
+		if errors.Is(err, errOAuthSessionNotPending) {
+			status = http.StatusConflict
+		}
+		http.Error(w, "Callback was not accepted. Return to HiRoute to check the sign-in status.", status)
+		return
+	}
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	if oauthError != "" {
+		_, _ = w.Write([]byte("Authorization was not completed. Return to HiRoute to try again.\n授权未完成,请返回 HiRoute 重试。"))
+		return
+	}
+	_, _ = w.Write([]byte("Authorization received. Return to HiRoute to check whether sign-in has completed.\n已收到授权,请返回 HiRoute 查看登录结果。"))
+}
diff --git a/internal/api/handlers/management/hiroute_oauth_callback_test.go b/internal/api/handlers/management/hiroute_oauth_callback_test.go
new file mode 100644
index 0000000..fdd19ac
--- /dev/null
+++ b/internal/api/handlers/management/hiroute_oauth_callback_test.go
@@ -0,0 +1,270 @@
+package management
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/auth/codex"
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/config"
+)
+
+func TestHiRouteBrowserCallbackValidationAndOneUse(t *testing.T) {
+	for _, provider := range []string{"codex", "anthropic"} {
+		t.Run(provider, func(t *testing.T) {
+			dir, state := t.TempDir(), "hiroute-validation-"+provider
+			RegisterOAuthSession(state, provider)
+			defer CancelOAuthSession(state)
+			path := "/auth/callback"
+			if provider == "anthropic" {
+				path = "/callback"
+			}
+			handler := hiRouteCallbackHandler(1455, provider, state, dir)
+			valid := path + "?state=" + state + "&code=private-test-code"
+			for _, input := range []struct{ method, path, host string }{
+				{"GET", path + "?state=foreign&code=private-test-code", "localhost:1455"},
+				{"GET", valid + "&state=" + state, "localhost:1455"},
+				{"GET", valid + "&code=second", "localhost:1455"},
+				{"GET", valid + "&error=denied", "localhost:1455"},
+				{"GET", path + "?state=" + state, "localhost:1455"},
+				{"GET", valid + "&bad=%ZZ", "localhost:1455"},
+				{"GET", valid, "foreign.test:1455"},
+				{"POST", valid, "localhost:1455"},
+				{"GET", "/foreign?state=" + state + "&code=test", "localhost:1455"},
+			} {
+				r := httptest.NewRequest(input.method, "http://localhost:1455"+input.path, nil)
+				r.Host = input.host
+				w := httptest.NewRecorder()
+				handler.ServeHTTP(w, r)
+				if w.Code != http.StatusBadRequest {
+					t.Fatalf("invalid callback accepted: %d", w.Code)
+				}
+				if strings.Contains(w.Body.String(), "private-test-code") || w.Header().Get("Location") != "" {
+					t.Fatal("callback escaped through response")
+				}
+			}
+			w := httptest.NewRecorder()
+			handler.ServeHTTP(w, httptest.NewRequest("GET", "http://localhost:1455"+valid, nil))
+			if w.Code != 200 || !strings.Contains(w.Body.String(), "Authorization received") || strings.Contains(w.Body.String(), "successful") {
+				t.Fatal("browser reception claimed login success")
+			}
+			if w.Header().Get("Referrer-Policy") != "no-referrer" || w.Header().Get("Cache-Control") != "no-store" {
+				t.Fatal("callback page did not protect the query")
+			}
+			file := filepath.Join(dir, ".oauth-"+provider+"-"+state+".oauth")
+			if err := os.Remove(file); err != nil {
+				t.Fatal(err)
+			}
+			if _, err := WriteOAuthCallbackFileForPendingSession(dir, provider, state, "replacement", ""); err == nil {
+				t.Fatal("manual input overwrote a consumed browser callback")
+			}
+			w = httptest.NewRecorder()
+			handler.ServeHTTP(w, httptest.NewRequest("GET", "http://localhost:1455"+valid, nil))
+			if w.Code != http.StatusConflict {
+				t.Fatal("repeated browser callback accepted")
+			}
+		})
+	}
+}
+
+func TestHiRouteCallbackAdmissionIsAtomicAndFailedWritesCanRetry(t *testing.T) {
+	dir, state := t.TempDir(), "hiroute-concurrent-callback"
+	RegisterOAuthSession(state, "codex")
+	defer CancelOAuthSession(state)
+	badPath := filepath.Join(dir, "not-a-directory")
+	if err := os.WriteFile(badPath, []byte("fixture"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := WriteOAuthCallbackFileForPendingSession(badPath, "codex", state, "code", ""); err == nil {
+		t.Fatal("failed write was accepted")
+	}
+	var accepted atomic.Int32
+	var group sync.WaitGroup
+	for i := 0; i < 16; i++ {
+		group.Add(1)
+		go func() {
+			defer group.Done()
+			if _, err := WriteOAuthCallbackFileForPendingSession(dir, "codex", state, "code", ""); err == nil {
+				accepted.Add(1)
+			}
+		}()
+	}
+	group.Wait()
+	if accepted.Load() != 1 {
+		t.Fatalf("accepted %d callbacks", accepted.Load())
+	}
+	for _, stale := range []string{"unknown-state", "cancelled-state", "expired-state"} {
+		RegisterOAuthSession(stale, "codex")
+		if stale == "expired-state" {
+			oauthSessions.mu.Lock()
+			s := oauthSessions.sessions[stale]
+			s.ExpiresAt = time.Now().Add(-time.Second)
+			oauthSessions.sessions[stale] = s
+			oauthSessions.mu.Unlock()
+		} else {
+			CancelOAuthSession(stale)
+		}
+		if _, err := WriteOAuthCallbackFileForPendingSession(dir, "codex", stale, "late-code", ""); err == nil {
+			t.Fatal("stale callback accepted")
+		}
+	}
+}
+
+func TestHiRouteLoopbackListenersReleaseTogether(t *testing.T) {
+	reservation, err := net.Listen("tcp4", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	port := reservation.Addr().(*net.TCPAddr).Port
+	_ = reservation.Close()
+	listeners, err := listenHiRouteCallbackLoopback(port)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, ln := range listeners {
+		if !ln.Addr().(*net.TCPAddr).IP.IsLoopback() {
+			t.Fatal("non-loopback callback listener")
+		}
+		_ = ln.Close()
+	}
+	forwarder, err := startHiRouteCallbackReceiver(port, "codex", "hiroute-loopback", t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	stopCallbackForwarderInstance(port, forwarder)
+	reopened, err := listenHiRouteCallbackLoopback(port)
+	if err != nil {
+		t.Fatalf("callback listener leaked: %v", err)
+	}
+	for _, ln := range reopened {
+		_ = ln.Close()
+	}
+	// An occupied IPv6 endpoint must release the already-opened IPv4 endpoint.
+	ipv6, err := net.Listen("tcp6", net.JoinHostPort("::1", strconv.Itoa(port)))
+	if err == nil {
+		defer ipv6.Close()
+		if opened, err := listenHiRouteCallbackLoopback(port); err == nil {
+			for _, ln := range opened {
+				_ = ln.Close()
+			}
+			t.Fatal("occupied IPv6 listener was ignored")
+		}
+		ipv4, err := net.Listen("tcp4", net.JoinHostPort("127.0.0.1", strconv.Itoa(port)))
+		if err != nil {
+			t.Fatal("partial IPv4 listener leaked")
+		}
+		_ = ipv4.Close()
+	}
+}
+
+func TestHiRouteOccupiedCallbackPortKeepsManualSession(t *testing.T) {
+	for _, provider := range []string{"codex", "anthropic"} {
+		port := codexCallbackPort
+		if provider == "anthropic" {
+			port = anthropicCallbackPort
+		}
+		occupied, err := net.Listen("tcp4", net.JoinHostPort("127.0.0.1", strconv.Itoa(port)))
+		if err == nil {
+			defer occupied.Close()
+		}
+		h := NewHandlerWithoutConfigFilePath(&config.Config{AuthDir: t.TempDir(), Port: 47111}, nil)
+		w := httptest.NewRecorder()
+		c, _ := gin.CreateTestContext(w)
+		c.Request = httptest.NewRequest("GET", "/auth-url?is_webui=true", nil)
+		if provider == "codex" {
+			h.RequestCodexToken(c)
+		} else {
+			h.RequestAnthropicToken(c)
+		}
+		var login map[string]string
+		if err := json.Unmarshal(w.Body.Bytes(), &login); err != nil {
+			t.Fatal(err)
+		}
+		if w.Code != 200 || login["hiroute_callback_mode"] != "manual" || login["url"] == "" || !IsOAuthSessionPending(login["state"], provider) {
+			t.Fatalf("occupied callback port lost the manual session: status %d", w.Code)
+		}
+		CancelOAuthSession(login["state"])
+	}
+}
+
+type hiRouteCountedCodexService struct {
+	fakeCodexOAuthService
+	exchanges atomic.Int32
+}
+
+func (s *hiRouteCountedCodexService) ExchangeCodeForTokens(ctx context.Context, code string, pkce *codex.PKCECodes) (*codex.CodexAuthBundle, error) {
+	s.exchanges.Add(1)
+	return s.fakeCodexOAuthService.ExchangeCodeForTokens(ctx, code, pkce)
+}
+
+func TestHiRouteCodexBrowserCompletionAndPortRelease(t *testing.T) {
+	service := &hiRouteCountedCodexService{}
+	original := newCodexOAuthService
+	newCodexOAuthService = func(*config.Config) codexOAuthService { return service }
+	defer func() { newCodexOAuthService = original }()
+	dir := t.TempDir()
+	h := NewHandlerWithoutConfigFilePath(&config.Config{AuthDir: dir, Port: 47111}, nil)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("GET", "/auth-url?is_webui=true", nil)
+	h.RequestCodexToken(c)
+	var login map[string]string
+	if err := json.Unmarshal(w.Body.Bytes(), &login); err != nil {
+		t.Fatal(err)
+	}
+	defer CancelOAuthSession(login["state"])
+	if w.Code != 200 || login["hiroute_callback_mode"] != "automatic" {
+		t.Fatal("browser callback listener did not start")
+	}
+	client := &http.Client{Transport: &http.Transport{Proxy: nil}, Timeout: 3 * time.Second}
+	defer client.CloseIdleConnections()
+	response, err := client.Get("http://localhost:1455/auth/callback?state=" + login["state"] + "&code=hiroute-test-code")
+	if err != nil {
+		t.Fatal(err)
+	}
+	body, _ := io.ReadAll(response.Body)
+	_ = response.Body.Close()
+	if response.StatusCode != 200 || strings.Contains(string(body), "successful") || strings.Contains(string(body), "hiroute-test-code") {
+		t.Fatal("incorrect browser callback response")
+	}
+	waitForOAuthSessionDone(t, login["state"])
+	if service.exchanges.Load() != 1 {
+		t.Fatal("authorization code exchange was replayed")
+	}
+	files, _ := filepath.Glob(filepath.Join(dir, "*.json"))
+	if len(files) != 1 {
+		t.Fatal("browser callback did not persist exactly one credential")
+	}
+	if _, err := WriteOAuthCallbackFileForPendingSession(dir, "codex", login["state"], "replacement", ""); err == nil {
+		t.Fatal("completed login accepted manual input")
+	}
+	listeners, err := listenHiRouteCallbackLoopback(codexCallbackPort)
+	if err != nil {
+		t.Fatal("completed login retained its callback port")
+	}
+	for _, ln := range listeners {
+		_ = ln.Close()
+	}
+}
+
+func TestHiRouteMainCallbackDoesNotReportFalseSuccess(t *testing.T) {
+	router := gin.New()
+	router.GET("/codex/callback", HiRouteBrowserOAuthCallback(t.TempDir(), "codex"))
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest("GET", "/codex/callback?state=unknown&code=secret", nil))
+	if w.Code != http.StatusConflict || strings.Contains(w.Body.String(), "successful") || strings.Contains(w.Body.String(), "secret") {
+		t.Fatal("unaccepted callback reported success")
+	}
+}
diff --git a/internal/api/handlers/management/local_machine_password_test.go b/internal/api/handlers/management/local_machine_password_test.go
new file mode 100644
index 0000000..74d027d
--- /dev/null
+++ b/internal/api/handlers/management/local_machine_password_test.go
@@ -0,0 +1,38 @@
+package management
+
+import (
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/config"
+	"golang.org/x/crypto/bcrypt"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestLocalMachinePasswordPreservesRemotePolicy(t *testing.T) {
+	t.Setenv("MANAGEMENT_PASSWORD", "")
+	machine := strings.Repeat("m", 40)
+	cfg := &config.Config{}
+	hash, errHash := bcrypt.GenerateFromPassword([]byte("different-config-secret"), bcrypt.MinCost)
+	if errHash != nil {
+		t.Fatal(errHash)
+	}
+	cfg.RemoteManagement.SecretKey = string(hash)
+	cfg.RemoteManagement.AllowRemote = false
+	handler := NewHandlerWithoutConfigFilePath(cfg, nil)
+	handler.SetLocalPassword(machine)
+	if ok, _, _ := handler.AuthenticateManagementKey("127.0.0.1", true, machine); !ok {
+		t.Fatal("local machine credential rejected")
+	}
+	if ok, code, _ := handler.AuthenticateManagementKey("198.51.100.1", false, machine); ok || code != http.StatusForbidden {
+		t.Fatal("remote policy overridden")
+	}
+	for _, invalid := range []string{"", "wrong", strings.Repeat("m", 39) + "n"} {
+		if ok, _, _ := handler.AuthenticateManagementKey("127.0.0.1", true, invalid); ok {
+			t.Fatal("invalid machine credential accepted")
+		}
+	}
+	handler.SetLocalPassword(strings.Repeat("n", 40))
+	if ok, _, _ := handler.AuthenticateManagementKey("127.0.0.2", true, machine); ok {
+		t.Fatal("old instance credential accepted")
+	}
+}
diff --git a/internal/api/handlers/management/oauth_sessions.go b/internal/api/handlers/management/oauth_sessions.go
index 336f9bb..9359040 100644
--- a/internal/api/handlers/management/oauth_sessions.go
+++ b/internal/api/handlers/management/oauth_sessions.go
@@ -33,13 +33,14 @@ var (
 )
 
 type oauthSession struct {
-	Provider  string
-	Status    string
-	Source    string
-	Metadata  map[string]any
-	Completed bool
-	CreatedAt time.Time
-	ExpiresAt time.Time
+	Provider          string
+	Status            string
+	Source            string
+	Metadata          map[string]any
+	Completed         bool
+	CallbackSubmitted bool
+	CreatedAt         time.Time
+	ExpiresAt         time.Time
 }
 
 type oauthSessionStore struct {
@@ -481,8 +482,24 @@ func WriteOAuthCallbackFileForPendingSession(authDir, provider, state, code, err
 	if err != nil {
 		return "", err
 	}
-	if !IsOAuthSessionPending(state, canonicalProvider) {
+	// Automatic browser callbacks and protected manual input share one admission.
+	// Hold it through atomic file publication; the consumer can remove that file,
+	// so its presence alone cannot prevent a second submission.
+	oauthSessions.mu.Lock()
+	defer oauthSessions.mu.Unlock()
+	oauthSessions.purgeExpiredLocked(time.Now())
+	session, ok := oauthSessions.sessions[state]
+	if !ok || session.Provider != canonicalProvider || session.Completed || session.Status != "" || session.CallbackSubmitted {
 		return "", errOAuthSessionNotPending
 	}
-	return writeOAuthCallbackFile(authDir, canonicalProvider, state, code, errorMessage)
+	if strings.TrimSpace(code) == "" && strings.TrimSpace(errorMessage) == "" {
+		return "", errInvalidOAuthState
+	}
+	path, err := writeOAuthCallbackFile(authDir, canonicalProvider, state, code, errorMessage)
+	if err != nil {
+		return "", err
+	}
+	session.CallbackSubmitted = true
+	oauthSessions.sessions[state] = session
+	return path, nil
 }
diff --git a/internal/api/server_routes.go b/internal/api/server_routes.go
index 546ca73..a878459 100644
--- a/internal/api/server_routes.go
+++ b/internal/api/server_routes.go
@@ -143,33 +143,9 @@ func (s *Server) setupRoutes() {
 	// OAuth callback endpoints (reuse main server port)
 	// These endpoints receive provider redirects and persist
 	// the short-lived code/state for the waiting goroutine.
-	s.engine.GET("/anthropic/callback", func(c *gin.Context) {
-		code := c.Query("code")
-		state := c.Query("state")
-		errStr := c.Query("error")
-		if errStr == "" {
-			errStr = c.Query("error_description")
-		}
-		if state != "" {
-			_, _ = managementHandlers.WriteOAuthCallbackFileForPendingSession(s.cfg.AuthDir, "anthropic", state, code, errStr)
-		}
-		c.Header("Content-Type", "text/html; charset=utf-8")
-		c.String(http.StatusOK, oauthCallbackSuccessHTML)
-	})
+	s.engine.GET("/anthropic/callback", managementHandlers.HiRouteBrowserOAuthCallback(s.cfg.AuthDir, "anthropic"))
 
-	s.engine.GET("/codex/callback", func(c *gin.Context) {
-		code := c.Query("code")
-		state := c.Query("state")
-		errStr := c.Query("error")
-		if errStr == "" {
-			errStr = c.Query("error_description")
-		}
-		if state != "" {
-			_, _ = managementHandlers.WriteOAuthCallbackFileForPendingSession(s.cfg.AuthDir, "codex", state, code, errStr)
-		}
-		c.Header("Content-Type", "text/html; charset=utf-8")
-		c.String(http.StatusOK, oauthCallbackSuccessHTML)
-	})
+	s.engine.GET("/codex/callback", managementHandlers.HiRouteBrowserOAuthCallback(s.cfg.AuthDir, "codex"))
 
 	s.engine.GET("/antigravity/callback", func(c *gin.Context) {
 		code := c.Query("code")
diff --git a/internal/auth/claude/hiroute_environment_proxy_test.go b/internal/auth/claude/hiroute_environment_proxy_test.go
new file mode 100644
index 0000000..3869b7e
--- /dev/null
+++ b/internal/auth/claude/hiroute_environment_proxy_test.go
@@ -0,0 +1,195 @@
+package claude
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/router-for-me/CLIProxyAPI/v8/sdk/config"
+)
+
+type hirouteOAuthDirectDialer struct{ calls atomic.Int32 }
+
+func (d *hirouteOAuthDirectDialer) Dial(network, address string) (net.Conn, error) {
+	return d.DialContext(context.Background(), network, address)
+}
+
+func (d *hirouteOAuthDirectDialer) DialContext(context.Context, string, string) (net.Conn, error) {
+	d.calls.Add(1)
+	return nil, errors.New("synthetic direct dial stopped before network")
+}
+
+// Each case needs a clean process because net/http snapshots environment proxy
+// settings once. Actual local CONNECT requests establish the selected route;
+// no provider requests, credentials, DNS resolution or token exchange are used.
+func TestHiRouteClaudeOAuthEnvironmentRouting(t *testing.T) {
+	if scenario := os.Getenv("HIROUTE_CLAUDE_OAUTH_PROXY_CASE"); scenario != "" {
+		testHiRouteClaudeOAuthEnvironmentRouting(t, scenario)
+		return
+	}
+	for _, scenario := range []string{
+		"upper", "lower", "upper-precedence", "no-proxy", "lower-no-proxy",
+		"per-target", "direct", "none", "explicit", "invalid-environment",
+		"invalid-explicit", "proxy-connect-failure", "selection-failure",
+		"all-proxy-ignored", "http-only-does-not-proxy-https", "http-inherit",
+		"malformed-https-upper", "malformed-https-lower", "malformed-http-upper",
+		"malformed-http-lower", "malformed-with-no-proxy", "malformed-upper-wins",
+		"valid-upper-ignores-malformed-lower", "valid-https-ignores-malformed-http",
+		"valid-http-ignores-malformed-https", "https-host-port-shorthand",
+	} {
+		t.Run(scenario, func(t *testing.T) {
+			command := exec.Command(os.Args[0], "-test.run=^TestHiRouteClaudeOAuthEnvironmentRouting$")
+			command.Env = []string{"HIROUTE_CLAUDE_OAUTH_PROXY_CASE=" + scenario}
+			if output, err := command.CombinedOutput(); err != nil {
+				t.Fatalf("isolated proxy case failed: %v\n%s", err, output)
+			}
+		})
+	}
+}
+
+func testHiRouteClaudeOAuthEnvironmentRouting(t *testing.T, scenario string) {
+	t.Helper()
+	var inheritedCalls, explicitCalls atomic.Int32
+	makeProxy := func(calls *atomic.Int32) *httptest.Server {
+		return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+			calls.Add(1)
+			if request.Method != http.MethodConnect || request.Host != "platform.claude.invalid:443" {
+				t.Errorf("proxy did not receive the exact OAuth target CONNECT")
+			}
+			// Deliberately fail the proxy hop. The caller must not retry directly.
+			w.WriteHeader(http.StatusBadGateway)
+		}))
+	}
+	inherited := makeProxy(&inheritedCalls)
+	defer inherited.Close()
+	explicit := makeProxy(&explicitCalls)
+	defer explicit.Close()
+	cfg := &config.SDKConfig{}
+	target := "https://platform.claude.invalid:443/v1/oauth/token"
+	wantInherited, wantExplicit, wantDirect := int32(1), int32(0), int32(0)
+	switch scenario {
+	case "upper":
+		t.Setenv("HTTPS_PROXY", inherited.URL)
+	case "lower":
+		t.Setenv("https_proxy", inherited.URL)
+	case "upper-precedence":
+		t.Setenv("HTTPS_PROXY", inherited.URL)
+		t.Setenv("https_proxy", explicit.URL)
+	case "malformed-https-upper", "malformed-https-lower", "malformed-http-upper", "malformed-http-lower", "malformed-with-no-proxy", "malformed-upper-wins":
+		key := "HTTPS_PROXY"
+		if strings.HasPrefix(scenario, "malformed-http-") {
+			key = "HTTP_PROXY"
+			target = "http://platform.claude.invalid:443/v1/oauth/token"
+		}
+		if strings.HasSuffix(scenario, "-lower") {
+			key = strings.ToLower(key)
+		}
+		t.Setenv(key, "http://%zz")
+		if scenario == "malformed-with-no-proxy" {
+			t.Setenv("NO_PROXY", "*")
+		}
+		if scenario == "malformed-upper-wins" {
+			t.Setenv("https_proxy", inherited.URL)
+		}
+		wantInherited = 0
+	case "valid-upper-ignores-malformed-lower":
+		t.Setenv("HTTPS_PROXY", inherited.URL)
+		t.Setenv("https_proxy", "http://%zz")
+	case "valid-https-ignores-malformed-http":
+		t.Setenv("HTTPS_PROXY", inherited.URL)
+		t.Setenv("HTTP_PROXY", "http://%zz")
+	case "valid-http-ignores-malformed-https":
+		t.Setenv("HTTP_PROXY", inherited.URL)
+		t.Setenv("HTTPS_PROXY", "http://%zz")
+		target = "http://platform.claude.invalid:443/v1/oauth/token"
+	case "https-host-port-shorthand":
+		t.Setenv("HTTPS_PROXY", strings.TrimPrefix(inherited.URL, "http://"))
+	case "no-proxy", "lower-no-proxy", "per-target":
+		t.Setenv("HTTPS_PROXY", inherited.URL)
+		key := "NO_PROXY"
+		if scenario == "lower-no-proxy" {
+			key = "no_proxy"
+		}
+		if scenario == "per-target" {
+			t.Setenv(key, "api.anthropic.invalid")
+		} else {
+			t.Setenv(key, "platform.claude.invalid")
+			wantInherited, wantDirect = 0, 1
+		}
+	case "direct", "none":
+		t.Setenv("HTTPS_PROXY", inherited.URL)
+		cfg.ProxyURL = scenario
+		wantInherited, wantDirect = 0, 1
+	case "explicit":
+		t.Setenv("HTTPS_PROXY", inherited.URL)
+		t.Setenv("NO_PROXY", "*") // Explicit settings take precedence over environment bypass.
+		cfg.ProxyURL = explicit.URL
+		wantInherited, wantExplicit = 0, 1
+	case "invalid-environment":
+		t.Setenv("HTTPS_PROXY", "ftp://127.0.0.1:1187")
+		wantInherited = 0
+	case "invalid-explicit":
+		t.Setenv("HTTPS_PROXY", inherited.URL)
+		cfg.ProxyURL = "ftp://127.0.0.1:1187"
+		wantInherited = 0
+	case "proxy-connect-failure":
+		t.Setenv("HTTPS_PROXY", inherited.URL)
+		inherited.Close()
+		wantInherited = 0
+	case "selection-failure":
+		t.Setenv("HTTP_PROXY", inherited.URL)
+		t.Setenv("REQUEST_METHOD", "POST") // Go refuses the unsafe CGI HTTP_PROXY route.
+		target = "http://platform.claude.invalid:443/v1/oauth/token"
+		wantInherited = 0
+	case "all-proxy-ignored":
+		t.Setenv("ALL_PROXY", inherited.URL)
+		t.Setenv("all_proxy", inherited.URL)
+		wantInherited, wantDirect = 0, 1
+	case "http-only-does-not-proxy-https":
+		t.Setenv("HTTP_PROXY", inherited.URL)
+		wantInherited, wantDirect = 0, 1
+	case "http-inherit":
+		t.Setenv("HTTP_PROXY", inherited.URL)
+		target = "http://platform.claude.invalid:443/v1/oauth/token"
+	default:
+		t.Fatal("unknown proxy case")
+	}
+	client := NewAnthropicHttpClient(cfg)
+	client.Timeout = time.Second
+	transport := client.Transport.(*utlsRoundTripper)
+	defer transport.CloseIdleConnections()
+	direct := &hirouteOAuthDirectDialer{}
+	if scenario != "explicit" {
+		transport.dialer = direct
+	}
+	makeRequest := func(target string) {
+		request, err := http.NewRequestWithContext(t.Context(), http.MethodPost, target, nil)
+		if err != nil {
+			t.Fatal("create synthetic request failed")
+		}
+		response, err := client.Do(request)
+		if response != nil {
+			_ = response.Body.Close()
+		}
+		if err == nil {
+			t.Fatal("synthetic network boundary unexpectedly succeeded")
+		}
+	}
+	makeRequest(target)
+	if scenario == "per-target" {
+		makeRequest("https://api.anthropic.invalid/api/oauth/profile")
+		wantDirect = 1
+	}
+	if inheritedCalls.Load() != wantInherited || explicitCalls.Load() != wantExplicit || direct.calls.Load() != wantDirect {
+		t.Fatalf("route counts: inherited=%d explicit=%d direct=%d; want %d/%d/%d",
+			inheritedCalls.Load(), explicitCalls.Load(), direct.calls.Load(), wantInherited, wantExplicit, wantDirect)
+	}
+}
diff --git a/internal/auth/claude/utls_transport.go b/internal/auth/claude/utls_transport.go
index 7d69d46..44da6d5 100644
--- a/internal/auth/claude/utls_transport.go
+++ b/internal/auth/claude/utls_transport.go
@@ -2,9 +2,11 @@ package claude
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"net"
 	"net/http"
+	"net/url"
 	"strings"
 	"time"
 
@@ -84,6 +86,13 @@ var claudeOAuthSessionCaches = internalcache.NewBoundedLRU[string, tls.ClientSes
 	nil,
 )
 
+// Inherited proxy routing shares a bounded pool by effective proxy, matching the
+// existing TLS session isolation. Failed proxy requests never retry directly.
+var claudeOAuthEnvironmentTransports = internalcache.NewBoundedLRU[string, *utlsRoundTripper](
+	claudeOAuthProxySessionCacheCapacity,
+	func(_ string, transport *utlsRoundTripper) { transport.CloseIdleConnections() },
+)
+
 func claudeOAuthSessionCache(proxyURL string) tls.ClientSessionCache {
 	return claudeOAuthSessionCaches.GetOrAdd(proxyURL, func() tls.ClientSessionCache {
 		return tls.NewLRUClientSessionCache(claudeOAuthSessionCacheCapacity)
@@ -166,7 +175,9 @@ func claudeOAuthTLSClientHelloSpec() *tls.ClientHelloSpec {
 // profile while retaining net/http proxy, cancellation, response parsing and
 // connection lifecycle semantics.
 type utlsRoundTripper struct {
-	dialer proxy.Dialer
+	dialer             proxy.Dialer
+	configurationError error
+	environmentProxy   func(*http.Request) (*url.URL, error)
 	// sessionCache is shared by every transport built for the same proxy, so
 	// short-lived ClaudeAuth instances can still resume, while resumption never
 	// crosses proxy boundaries.
@@ -177,37 +188,47 @@ type utlsRoundTripper struct {
 func newUtlsRoundTripper(cfg *config.SDKConfig) *utlsRoundTripper {
 	var dialer proxy.Dialer = proxy.Direct
 	var proxyURL string
+	var configurationError error
+	mode := proxyutil.ModeInherit
 	if cfg != nil {
 		proxyURL = cfg.ProxyURL
-		proxyDialer, mode, errBuild := proxyutil.BuildDialer(cfg.ProxyURL)
+		proxyDialer, selectedMode, errBuild := proxyutil.BuildDialer(cfg.ProxyURL)
+		mode = selectedMode
 		if errBuild != nil {
 			log.Errorf("failed to configure proxy dialer for %q: %v", proxyutil.Redact(cfg.ProxyURL), errBuild)
+			configurationError = errors.New("invalid claude oauth proxy configuration")
 		} else if mode != proxyutil.ModeInherit && proxyDialer != nil {
 			dialer = proxyDialer
 		}
 	}
 
 	roundTripper := &utlsRoundTripper{
-		dialer:       dialer,
-		sessionCache: claudeOAuthSessionCache(proxyURL),
+		dialer:             dialer,
+		configurationError: configurationError,
+		sessionCache:       claudeOAuthSessionCache(proxyURL),
+	}
+	if mode == proxyutil.ModeInherit {
+		// Use the same target-aware HTTP(S)_PROXY/NO_PROXY policy as inference.
+		// Setting Transport.Proxy would bypass the custom uTLS CONNECT dialer.
+		roundTripper.environmentProxy = proxyutil.EnvironmentProxyFunc()
 	}
 	roundTripper.transport = &http.Transport{
 		ForceAttemptHTTP2: false,
+		DialContext:       roundTripper.dialContext,
 		DialTLSContext:    roundTripper.dialTLSContext,
 	}
 	return roundTripper
 }
 
-func (t *utlsRoundTripper) dialTLSContext(ctx context.Context, network, addr string) (net.Conn, error) {
-	var (
-		conn net.Conn
-		err  error
-	)
+func (t *utlsRoundTripper) dialContext(ctx context.Context, network, addr string) (net.Conn, error) {
 	if contextDialer, ok := t.dialer.(proxy.ContextDialer); ok {
-		conn, err = contextDialer.DialContext(ctx, network, addr)
-	} else {
-		conn, err = t.dialer.Dial(network, addr)
+		return contextDialer.DialContext(ctx, network, addr)
 	}
+	return t.dialer.Dial(network, addr)
+}
+
+func (t *utlsRoundTripper) dialTLSContext(ctx context.Context, network, addr string) (net.Conn, error) {
+	conn, err := t.dialContext(ctx, network, addr)
 	if err != nil {
 		return nil, fmt.Errorf("claude oauth tls: dial upstream: %w", err)
 	}
@@ -242,6 +263,24 @@ func (t *utlsRoundTripper) dialTLSContext(ctx context.Context, network, addr str
 }
 
 func (t *utlsRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
+	if t.configurationError != nil {
+		return nil, t.configurationError
+	}
+	if t.environmentProxy != nil {
+		selected, err := t.environmentProxy(req)
+		if err != nil {
+			return nil, errors.New("failed to select claude oauth environment proxy")
+		}
+		if selected != nil {
+			if !proxyutil.ValidRequestProxy(selected.String()) {
+				return nil, errors.New("invalid claude oauth environment proxy")
+			}
+			transport := claudeOAuthEnvironmentTransports.GetOrAdd(selected.String(), func() *utlsRoundTripper {
+				return newUtlsRoundTripper(&config.SDKConfig{ProxyURL: selected.String()})
+			})
+			return transport.RoundTrip(req)
+		}
+	}
 	return t.transport.RoundTrip(req)
 }
 
diff --git a/internal/modeldiscovery/diagnostics.go b/internal/modeldiscovery/diagnostics.go
new file mode 100644
index 0000000..c444f23
--- /dev/null
+++ b/internal/modeldiscovery/diagnostics.go
@@ -0,0 +1,285 @@
+// Package modeldiscovery retains bounded, secret-free observations for the
+// existing authenticated management response. It never logs raw errors or I/O.
+package modeldiscovery
+
+import (
+	"context"
+	"crypto/x509"
+	"errors"
+	"net"
+	"os"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/router-for-me/CLIProxyAPI/v8/sdk/proxyutil"
+)
+
+const capacity = 128
+
+type Phase string
+type Outcome string
+type Reason string
+
+const (
+	Credentials              Phase   = "credentials"
+	ClientVersion            Phase   = "client_version"
+	Request                  Phase   = "request"
+	Response                 Phase   = "response"
+	Catalog                  Phase   = "catalog"
+	Registration             Phase   = "registration"
+	Entered                  Outcome = "entered"
+	Completed                Outcome = "completed"
+	Failed                   Outcome = "failed"
+	Discarded                Outcome = "discarded"
+	NoReason                 Reason  = ""
+	MissingAccessToken       Reason  = "missing_access_token"
+	ClientVersionUnavailable Reason  = "client_version_unavailable"
+	Cancelled                Reason  = "cancelled"
+	Timeout                  Reason  = "timeout"
+	DNSFailure               Reason  = "dns_failure"
+	ConnectFailure           Reason  = "connect_failure"
+	ProxyFailure             Reason  = "proxy_failure"
+	ProxyRejected            Reason  = "proxy_rejected"
+	TLSFailure               Reason  = "tls_failure"
+	TransportFailure         Reason  = "transport_failure"
+	HTTPRejected             Reason  = "http_rejected"
+	BodyReadFailure          Reason  = "body_read_failure"
+	ResponseTooLarge         Reason  = "response_too_large"
+	InvalidCatalog           Reason  = "invalid_catalog"
+	InvalidModelID           Reason  = "invalid_model_id"
+	DuplicateModelID         Reason  = "duplicate_model_id"
+	EmptyCatalog             Reason  = "empty_catalog"
+	EmptyAfterFiltering      Reason  = "empty_after_filtering"
+	AccountMissing           Reason  = "account_missing"
+	AccountDisabled          Reason  = "account_disabled"
+	AccountChanged           Reason  = "account_changed"
+)
+
+type PhaseTiming struct {
+	Phase      Phase   `json:"phase"`
+	Outcome    Outcome `json:"outcome"`
+	ElapsedMS  uint64  `json:"elapsed_ms"`
+	Reason     Reason  `json:"reason,omitempty"`
+	ModelCount *uint64 `json:"model_count,omitempty"`
+}
+
+type Attempt struct {
+	ID                       uint64        `json:"attempt_id"`
+	Phase                    Phase         `json:"phase"`
+	Outcome                  Outcome       `json:"outcome"`
+	Reason                   Reason        `json:"reason,omitempty"`
+	ElapsedMS                uint64        `json:"elapsed_ms"`
+	PhaseElapsedMS           uint64        `json:"phase_elapsed_ms"`
+	HTTPStatus               *int          `json:"http_status,omitempty"`
+	ProxyStatus              *int          `json:"proxy_status,omitempty"`
+	ModelCount               *uint64       `json:"model_count,omitempty"`
+	GenerationMatches        *bool         `json:"generation_matches,omitempty"`
+	RegistrationEpochMatches *bool         `json:"registration_epoch_matches,omitempty"`
+	Timings                  []PhaseTiming `json:"timings"`
+}
+
+type Snapshot struct {
+	Schema              string   `json:"schema"`
+	ProcessID           int      `json:"process_id"`
+	EvictedAccounts     uint64   `json:"evicted_accounts"`
+	FirstFailure        *Attempt `json:"first_failure"`
+	Latest              *Attempt `json:"latest"`
+	RegistrationPending bool     `json:"registration_pending"`
+	revision            uint64
+}
+
+type entry struct {
+	first   *Attempt
+	latest  Attempt
+	updated time.Time
+}
+
+var store = struct {
+	sync.Mutex
+	entries  map[string]*entry
+	evicted  uint64
+	active   map[string]uint64
+	revision uint64
+}{entries: make(map[string]*entry), active: make(map[string]uint64)}
+var nextID atomic.Uint64
+
+type contextKey struct{}
+
+// Trace belongs to one synchronous discovery/registration attempt, not a goroutine
+// shared by independent registrations. Only immutable copies enter the store.
+type Trace struct {
+	account      string
+	started      time.Time
+	phaseStarted time.Time
+	value        Attempt
+}
+
+func Begin(account string) *Trace {
+	return &Trace{account: account, started: time.Now(), value: Attempt{ID: nextID.Add(1), Timings: []PhaseTiming{}}}
+}
+
+func WithTrace(ctx context.Context, trace *Trace) context.Context {
+	return context.WithValue(ctx, contextKey{}, trace)
+}
+
+func FromContext(ctx context.Context) *Trace {
+	trace, _ := ctx.Value(contextKey{}).(*Trace)
+	return trace
+}
+
+func (t *Trace) Enter(phase Phase) {
+	t.phaseStarted = time.Now()
+	t.value.Phase, t.value.Outcome, t.value.Reason = phase, Entered, NoReason
+	t.value.ElapsedMS, t.value.PhaseElapsedMS = millis(time.Since(t.started)), 0
+	t.publish()
+}
+
+func (t *Trace) End(outcome Outcome, reason Reason) {
+	t.value.Outcome, t.value.Reason = outcome, reason
+	t.value.ElapsedMS, t.value.PhaseElapsedMS = millis(time.Since(t.started)), millis(time.Since(t.phaseStarted))
+	if len(t.value.Timings) < 6 {
+		t.value.Timings = append(t.value.Timings, PhaseTiming{t.value.Phase, outcome, t.value.PhaseElapsedMS, reason, t.value.ModelCount})
+	}
+	t.publish()
+}
+
+func (t *Trace) HTTP(status int)  { t.value.HTTPStatus = &status }
+func (t *Trace) Models(count int) { value := uint64(count); t.value.ModelCount = &value }
+
+func (t *Trace) RegistrationChecks(generation, epoch bool) {
+	t.value.GenerationMatches, t.value.RegistrationEpochMatches = &generation, &epoch
+}
+
+// Transport retains only closed categories. URLs, hostnames, proxy credentials
+// and arbitrary error strings are never copied into an observation.
+func (t *Trace) Transport(err error) {
+	var proxyError *proxyutil.ConnectStatusError
+	if errors.As(err, &proxyError) {
+		status := proxyError.StatusCode
+		t.value.ProxyStatus = &status
+		t.End(Failed, ProxyRejected)
+		return
+	}
+	reason := TransportFailure
+	var dns *net.DNSError
+	var network *net.OpError
+	var timeout net.Error
+	var unknownCA x509.UnknownAuthorityError
+	var hostname x509.HostnameError
+	var invalidCertificate x509.CertificateInvalidError
+	switch {
+	case errors.Is(err, context.Canceled):
+		reason = Cancelled
+	case errors.Is(err, context.DeadlineExceeded):
+		reason = Timeout
+	case errors.As(err, &timeout) && timeout.Timeout():
+		reason = Timeout
+	case errors.As(err, &dns):
+		reason = DNSFailure
+	case errors.As(err, &unknownCA), errors.As(err, &hostname), errors.As(err, &invalidCertificate):
+		reason = TLSFailure
+	case errors.As(err, &network) && network.Op == "dial":
+		reason = ConnectFailure
+	}
+	// The pinned transports own these fixed wrappers. Inspecting them refines a
+	// category without retaining the nested message or guessing an upstream status.
+	if reason == TransportFailure || reason == ConnectFailure {
+		for cause := err; cause != nil; cause = errors.Unwrap(cause) {
+			message := cause.Error()
+			switch {
+			case strings.HasPrefix(message, "utls: TLS handshake:"), strings.HasPrefix(message, "HTTPS proxy TLS handshake failed:"):
+				reason = TLSFailure
+			case strings.HasPrefix(message, "dial HTTP proxy failed:"), strings.HasPrefix(message, "write CONNECT request failed:"), strings.HasPrefix(message, "read CONNECT response failed:"):
+				reason = ProxyFailure
+			}
+		}
+	}
+	t.End(Failed, reason)
+}
+
+func (t *Trace) publish() {
+	if t.account == "" || len(t.account) > 4096 {
+		return
+	}
+	store.Lock()
+	defer store.Unlock()
+	store.revision++
+	current := store.entries[t.account]
+	if current == nil {
+		if len(store.entries) == capacity {
+			var oldest string
+			var id uint64 = ^uint64(0)
+			for key, value := range store.entries {
+				if value.latest.ID < id {
+					oldest, id = key, value.latest.ID
+				}
+			}
+			delete(store.entries, oldest)
+			store.evicted++
+		}
+		current = &entry{}
+		store.entries[t.account] = current
+	}
+	if current.first == nil && (t.value.Outcome == Failed || t.value.Outcome == Discarded) {
+		copy := clone(t.value)
+		current.first = &copy
+	}
+	if t.value.ID >= current.latest.ID {
+		current.latest, current.updated = clone(t.value), time.Now()
+	}
+}
+
+func Read(account string) Snapshot {
+	store.Lock()
+	defer store.Unlock()
+	result := Snapshot{Schema: "hiroute.cpa-model-discovery/v1", ProcessID: os.Getpid(), EvictedAccounts: store.evicted,
+		RegistrationPending: store.active[account] != 0, revision: store.revision}
+	if current := store.entries[account]; current != nil {
+		latest := clone(current.latest)
+		if latest.Outcome == Entered {
+			delta := millis(time.Since(current.updated))
+			latest.ElapsedMS += delta
+			latest.PhaseElapsedMS += delta
+		}
+		result.Latest = &latest
+		if current.first != nil {
+			first := clone(*current.first)
+			result.FirstFailure = &first
+		}
+	}
+	return result
+}
+
+func clone(value Attempt) Attempt {
+	if value.GenerationMatches != nil {
+		copy := *value.GenerationMatches
+		value.GenerationMatches = &copy
+	}
+	if value.RegistrationEpochMatches != nil {
+		copy := *value.RegistrationEpochMatches
+		value.RegistrationEpochMatches = &copy
+	}
+	if value.HTTPStatus != nil {
+		copy := *value.HTTPStatus
+		value.HTTPStatus = &copy
+	}
+	if value.ProxyStatus != nil {
+		copy := *value.ProxyStatus
+		value.ProxyStatus = &copy
+	}
+	if value.ModelCount != nil {
+		copy := *value.ModelCount
+		value.ModelCount = &copy
+	}
+	value.Timings = append([]PhaseTiming{}, value.Timings...)
+	for index := range value.Timings {
+		if value.Timings[index].ModelCount != nil {
+			copy := *value.Timings[index].ModelCount
+			value.Timings[index].ModelCount = &copy
+		}
+	}
+	return value
+}
+func millis(value time.Duration) uint64 { return uint64(value.Milliseconds()) }
diff --git a/internal/modeldiscovery/diagnostics_test.go b/internal/modeldiscovery/diagnostics_test.go
new file mode 100644
index 0000000..9c9d1d2
--- /dev/null
+++ b/internal/modeldiscovery/diagnostics_test.go
@@ -0,0 +1,100 @@
+package modeldiscovery
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/router-for-me/CLIProxyAPI/v8/sdk/proxyutil"
+)
+
+func TestHiRouteDiscoveryFirstFailureSurvivesRecoveryAndOutOfOrderCompletion(t *testing.T) {
+	id := "private-account-must-not-leak"
+	first := Begin(id)
+	first.Enter(ClientVersion)
+	first.End(Failed, ClientVersionUnavailable)
+	second := Begin(id)
+	second.Enter(Catalog)
+	second.Models(9)
+	second.End(Completed, NoReason)
+	first.Enter(Registration)
+	first.End(Discarded, AccountChanged)
+	snapshot := Read(id)
+	if snapshot.FirstFailure == nil || snapshot.FirstFailure.Reason != ClientVersionUnavailable || snapshot.Latest.ID != second.value.ID {
+		t.Fatal("first failure or latest attempt lost")
+	}
+	if *snapshot.Latest.ModelCount != 9 {
+		t.Fatal("model count lost")
+	}
+	*snapshot.Latest.ModelCount = 123
+	if *Read(id).Latest.ModelCount != 9 {
+		t.Fatal("snapshot mutates retained observation")
+	}
+	encoded, _ := json.Marshal(snapshot)
+	if strings.Contains(string(encoded), id) || strings.Contains(string(encoded), "access_token") {
+		t.Fatal("private identity leaked")
+	}
+}
+
+func TestHiRouteDiscoveryTransportCategoriesNeverRetainRawErrors(t *testing.T) {
+	for index, item := range []struct {
+		err    error
+		reason Reason
+		status int
+	}{
+		{context.DeadlineExceeded, Timeout, 0},
+		{context.Canceled, Cancelled, 0},
+		{&net.DNSError{Name: "private-host", Err: "private-token"}, DNSFailure, 0},
+		{&net.OpError{Op: "dial", Err: fmt.Errorf("private-token")}, ConnectFailure, 0},
+		{fmt.Errorf("utls: TLS handshake: private-token"), TLSFailure, 0},
+		{fmt.Errorf("read CONNECT response failed: private-token"), ProxyFailure, 0},
+		{fmt.Errorf("wrapped: %w", &proxyutil.ConnectStatusError{StatusCode: 503}), ProxyRejected, 503},
+		{fmt.Errorf("private-token"), TransportFailure, 0},
+	} {
+		id := fmt.Sprintf("transport-%d", index)
+		trace := Begin(id)
+		trace.Enter(Request)
+		trace.Transport(item.err)
+		value := Read(id).Latest
+		if value.Reason != item.reason {
+			t.Fatalf("case %d reason=%s", index, value.Reason)
+		}
+		if item.status != 0 && (value.ProxyStatus == nil || *value.ProxyStatus != item.status || value.HTTPStatus != nil) {
+			t.Fatal("proxy status was mislabeled as upstream status")
+		}
+		data, _ := json.Marshal(value)
+		if strings.Contains(string(data), "private-token") || strings.Contains(string(data), "private-host") {
+			t.Fatal("raw transport data leaked")
+		}
+	}
+}
+
+func TestHiRouteDiscoveryStorageAndPhaseHistoryAreBounded(t *testing.T) {
+	for index := 0; index < capacity+5; index++ {
+		trace := Begin(fmt.Sprintf("bounded-%d", index))
+		for phase := 0; phase < 10; phase++ {
+			trace.Enter(Request)
+			trace.End(Completed, NoReason)
+		}
+	}
+	store.Lock()
+	count := len(store.entries)
+	store.Unlock()
+	if count > capacity || Read("bounded-132").EvictedAccounts == 0 {
+		t.Fatal("unbounded account history")
+	}
+	latest := Read("bounded-132").Latest
+	if latest == nil || len(latest.Timings) != 6 {
+		t.Fatal("unbounded phase history")
+	}
+	trace := Begin("progress")
+	trace.Enter(Request)
+	time.Sleep(time.Millisecond)
+	if Read("progress").Latest.Outcome != Entered || Read("progress").Latest.ElapsedMS == 0 {
+		t.Fatal("blocked phase is not observable")
+	}
+}
diff --git a/internal/modeldiscovery/registration.go b/internal/modeldiscovery/registration.go
new file mode 100644
index 0000000..9b51136
--- /dev/null
+++ b/internal/modeldiscovery/registration.go
@@ -0,0 +1,39 @@
+package modeldiscovery
+
+import "sync"
+
+// Registering spans the whole registration, including the gap between a
+// discarded attempt and its bounded handoff. Entries live only while work runs;
+// evicting diagnostic history cannot erase an in-flight registration.
+func Registering(account string) func() {
+	if account == "" || len(account) > 4096 {
+		return func() {}
+	}
+	store.Lock()
+	store.active[account]++
+	store.revision++
+	store.Unlock()
+	var once sync.Once
+	return func() {
+		once.Do(func() {
+			store.Lock()
+			defer store.Unlock()
+			store.active[account]--
+			if store.active[account] == 0 {
+				delete(store.active, account)
+			}
+			store.revision++
+		})
+	}
+}
+
+// ReadCatalog brackets a local catalog read without holding the diagnostics
+// mutex across registry work. A transition during the read is pending for this
+// response, so mixed snapshots cannot turn an empty read into a terminal result.
+func ReadCatalog(account string, read func()) Snapshot {
+	before := Read(account)
+	read()
+	after := Read(account)
+	after.RegistrationPending = before.RegistrationPending || after.RegistrationPending || before.revision != after.revision
+	return after
+}
diff --git a/internal/modeldiscovery/registration_test.go b/internal/modeldiscovery/registration_test.go
new file mode 100644
index 0000000..55ff881
--- /dev/null
+++ b/internal/modeldiscovery/registration_test.go
@@ -0,0 +1,94 @@
+package modeldiscovery
+
+import (
+	"testing"
+
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/registry"
+)
+
+func TestHiRouteRegistrationHandoffRemainsPendingBetweenAttempts(t *testing.T) {
+	const account = "handoff-gap"
+	gap, resume, finished := make(chan struct{}), make(chan struct{}), make(chan struct{})
+	go func() {
+		defer close(finished)
+		done := Registering(account)
+		defer done()
+		first := Begin(account)
+		first.Enter(Registration)
+		first.End(Discarded, AccountChanged)
+		close(gap)
+		<-resume
+		second := Begin(account)
+		second.Enter(Registration)
+		second.Models(1)
+		second.End(Completed, NoReason)
+	}()
+	<-gap
+	snapshot := ReadCatalog(account, func() {})
+	close(resume)
+	<-finished
+	if !snapshot.RegistrationPending || snapshot.Latest == nil || snapshot.Latest.Outcome != Discarded {
+		t.Fatal("discarded first attempt hid the pending handoff")
+	}
+	settled := ReadCatalog(account, func() {})
+	if settled.RegistrationPending || settled.Latest == nil || settled.Latest.ModelCount == nil || *settled.Latest.ModelCount != 1 {
+		t.Fatal("completed registration did not become quiescent")
+	}
+}
+
+func TestHiRouteCatalogReadDetectsConcurrentRegistrationCompletion(t *testing.T) {
+	const account = "mixed-catalog-snapshot"
+	reg := registry.GetGlobalRegistry()
+	defer reg.UnregisterClient(account)
+	first := Begin(account)
+	first.Enter(Request)
+	first.End(Failed, Timeout)
+	read, resume := make(chan struct{}), make(chan struct{})
+	result := make(chan Snapshot, 1)
+	var models []*registry.ModelInfo
+	go func() {
+		result <- ReadCatalog(account, func() {
+			models = reg.GetModelsForClient(account)
+			close(read)
+			<-resume
+		})
+	}()
+	<-read
+	done := Registering(account)
+	second := Begin(account)
+	second.Enter(Registration)
+	reg.RegisterClient(account, "codex", []*registry.ModelInfo{{ID: "current-model", Object: "model", Type: "codex"}})
+	second.Models(1)
+	second.End(Completed, NoReason)
+	done()
+	close(resume)
+	snapshot := <-result
+	if len(models) != 0 || snapshot.Latest == nil || snapshot.Latest.ModelCount == nil || *snapshot.Latest.ModelCount != 1 || !snapshot.RegistrationPending {
+		t.Fatal("mixed empty/success response was presented as quiescent")
+	}
+	settled := ReadCatalog(account, func() { models = reg.GetModelsForClient(account) })
+	if len(models) != 1 || settled.RegistrationPending {
+		t.Fatal("next stable read did not recover")
+	}
+}
+
+func TestHiRouteRegistrationTrackingIsAccountScopedAndSurvivesHistoryEviction(t *testing.T) {
+	const account = "active-during-eviction"
+	first, second := Registering(account), Registering(account)
+	for index := 0; index < capacity+1; index++ {
+		trace := Begin(string(rune(index + 1000)))
+		trace.Enter(Request)
+	}
+	first()
+	first() // Registration task completion and batch cleanup may both finish it.
+	if !Read(account).RegistrationPending || Read("other-account").RegistrationPending {
+		t.Fatal("overlapping work or account scope lost")
+	}
+	second()
+	store.Lock()
+	_, retained := store.active[account]
+	store.Unlock()
+	if retained || Read(account).RegistrationPending {
+		t.Fatal("finished registration state leaked")
+	}
+}
diff --git a/internal/runtime/executor/codex_model_diagnostics_test.go b/internal/runtime/executor/codex_model_diagnostics_test.go
new file mode 100644
index 0000000..30e6697
--- /dev/null
+++ b/internal/runtime/executor/codex_model_diagnostics_test.go
@@ -0,0 +1,61 @@
+package executor
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
+	cliproxyauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
+)
+
+type discoveryDiagnosticTransport struct {
+	status int
+	body   string
+}
+
+func (d discoveryDiagnosticTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	return &http.Response{StatusCode: d.status, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(d.body)), Request: req}, nil
+}
+
+func TestHiRouteCodexDiscoveryFailurePhaseAndSafeResponseFacts(t *testing.T) {
+	for _, item := range []struct {
+		name   string
+		status int
+		body   string
+		phase  modeldiscovery.Phase
+		reason modeldiscovery.Reason
+	}{
+		{"unauthorized", 401, `{"error":"private-token"}`, modeldiscovery.Response, modeldiscovery.HTTPRejected},
+		{"forbidden", 403, `private-token`, modeldiscovery.Response, modeldiscovery.HTTPRejected},
+		{"invalid-json", 200, `private-token`, modeldiscovery.Catalog, modeldiscovery.InvalidCatalog},
+		{"duplicate", 200, `{"models":[{"slug":"m"},{"slug":"m"}]}`, modeldiscovery.Catalog, modeldiscovery.DuplicateModelID},
+		{"empty", 200, `{"models":[]}`, modeldiscovery.Catalog, modeldiscovery.EmptyCatalog},
+	} {
+		t.Run(item.name, func(t *testing.T) {
+			id := "diagnostic-" + item.name
+			a := &cliproxyauth.Auth{ID: id, Metadata: map[string]any{"access_token": "private-token", "hiroute_client_version": "0.999.0"}}
+			ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", http.RoundTripper(discoveryDiagnosticTransport{item.status, item.body}))
+			_, err := NewCodexExecutor(nil).DiscoverModels(ctx, a, nil)
+			value := modeldiscovery.Read(id).Latest
+			if value == nil || value.Phase != item.phase || value.Reason != item.reason || value.HTTPStatus == nil || *value.HTTPStatus != item.status {
+				t.Fatal("failure boundary or HTTP status lost")
+			}
+			if item.name == "empty" {
+				if err != nil || value.Outcome != modeldiscovery.Completed || value.ModelCount == nil || *value.ModelCount != 0 {
+					t.Fatal("valid empty catalog mislabeled as failed transport")
+				}
+			} else if err == nil {
+				t.Fatal("invalid discovery succeeded")
+			}
+		})
+	}
+	id := "missing-version-diagnostic"
+	_, err := NewCodexExecutor(nil).DiscoverModels(context.Background(), &cliproxyauth.Auth{ID: id, Metadata: map[string]any{"access_token": "private-token"}}, nil)
+	value := modeldiscovery.Read(id).Latest
+	if err == nil || value.Phase != modeldiscovery.ClientVersion || value.Reason != modeldiscovery.ClientVersionUnavailable || value.HTTPStatus != nil {
+		t.Fatal("local version failure confused with an upstream response")
+	}
+}
diff --git a/internal/runtime/executor/codex_models.go b/internal/runtime/executor/codex_models.go
new file mode 100644
index 0000000..f17845a
--- /dev/null
+++ b/internal/runtime/executor/codex_models.go
@@ -0,0 +1,173 @@
+package executor
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/registry"
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/runtime/executor/helps"
+	cliproxyauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
+)
+
+// DiscoverModels uses the same account, proxy and TLS transport as Codex requests.
+// The remote list controls membership; bundled metadata only enriches matching IDs.
+func (e *CodexExecutor) DiscoverModels(ctx context.Context, auth *cliproxyauth.Auth, known []*registry.ModelInfo) ([]*registry.ModelInfo, error) {
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	trace := modeldiscovery.FromContext(ctx)
+	if trace == nil {
+		id := ""
+		if auth != nil {
+			id = auth.ID
+		}
+		trace = modeldiscovery.Begin(id)
+	}
+	trace.Enter(modeldiscovery.Credentials)
+	token, _ := codexCreds(auth)
+	if strings.TrimSpace(token) == "" {
+		trace.End(modeldiscovery.Failed, modeldiscovery.MissingAccessToken)
+		return nil, fmt.Errorf("codex model discovery: missing access token")
+	}
+	trace.End(modeldiscovery.Completed, modeldiscovery.NoReason)
+	trace.Enter(modeldiscovery.ClientVersion)
+	version, err := codexModelDiscoveryVersion(auth)
+	if err != nil {
+		trace.End(modeldiscovery.Failed, modeldiscovery.ClientVersionUnavailable)
+		return nil, err
+	}
+	trace.End(modeldiscovery.Completed, modeldiscovery.NoReason)
+	trace.Enter(modeldiscovery.Request)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://chatgpt.com/backend-api/codex/models?client_version="+url.QueryEscape(version), nil)
+	if err != nil {
+		trace.Transport(err)
+		return nil, err
+	}
+	applyCodexHeadersFromSources(req, auth, token, false, e.cfg, nil)
+	client := helps.NewUtlsHTTPClient(ctx, e.cfg, auth, 5*time.Second)
+	// Never forward subscription credentials to a redirect target.
+	client.CheckRedirect = func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }
+	resp, err := client.Do(req)
+	if err != nil {
+		trace.Transport(err)
+		return nil, fmt.Errorf("codex model discovery: transport failed")
+	}
+	defer resp.Body.Close()
+	trace.HTTP(resp.StatusCode)
+	trace.End(modeldiscovery.Completed, modeldiscovery.NoReason)
+	trace.Enter(modeldiscovery.Response)
+	if resp.StatusCode != http.StatusOK {
+		trace.End(modeldiscovery.Failed, modeldiscovery.HTTPRejected)
+		return nil, fmt.Errorf("codex model discovery: HTTP %d", resp.StatusCode)
+	}
+	const limit = 16 << 20
+	body, err := io.ReadAll(io.LimitReader(resp.Body, limit+1))
+	if err != nil || len(body) > limit {
+		reason := modeldiscovery.BodyReadFailure
+		if len(body) > limit {
+			reason = modeldiscovery.ResponseTooLarge
+		}
+		if ctx.Err() == context.DeadlineExceeded {
+			reason = modeldiscovery.Timeout
+		}
+		if ctx.Err() == context.Canceled {
+			reason = modeldiscovery.Cancelled
+		}
+		trace.End(modeldiscovery.Failed, reason)
+		return nil, fmt.Errorf("codex model discovery: unreadable or oversized catalog")
+	}
+	trace.End(modeldiscovery.Completed, modeldiscovery.NoReason)
+	trace.Enter(modeldiscovery.Catalog)
+	var catalog struct {
+		Models []struct {
+			Slug             string   `json:"slug"`
+			DisplayName      string   `json:"display_name"`
+			Description      string   `json:"description"`
+			ContextWindow    int      `json:"context_window"`
+			MaxContextWindow int      `json:"max_context_window"`
+			InputModalities  []string `json:"input_modalities"`
+			Reasoning        []struct {
+				Effort string `json:"effort"`
+			} `json:"supported_reasoning_levels"`
+		} `json:"models"`
+	}
+	if json.Unmarshal(body, &catalog) != nil || catalog.Models == nil {
+		trace.End(modeldiscovery.Failed, modeldiscovery.InvalidCatalog)
+		return nil, fmt.Errorf("codex model discovery: invalid catalog")
+	}
+	byID := make(map[string]*registry.ModelInfo, len(known))
+	for _, m := range known {
+		if m != nil {
+			byID[m.ID] = m
+		}
+	}
+	models := make([]*registry.ModelInfo, 0, len(catalog.Models))
+	seen := make(map[string]bool)
+	for _, remote := range catalog.Models {
+		id := strings.TrimSpace(remote.Slug)
+		if id == "" || seen[id] {
+			reason := modeldiscovery.InvalidModelID
+			if seen[id] {
+				reason = modeldiscovery.DuplicateModelID
+			}
+			trace.End(modeldiscovery.Failed, reason)
+			return nil, fmt.Errorf("codex model discovery: invalid or duplicate model ID")
+		}
+		seen[id] = true
+		m := registry.ModelInfo{ID: id, Object: "model", OwnedBy: "openai", Type: "codex"}
+		if base := byID[id]; base != nil {
+			m = *base
+		}
+		m.DisplayName, m.Description = remote.DisplayName, remote.Description
+		m.ContextLength, m.MaxContextLength = remote.ContextWindow, remote.MaxContextWindow
+		if m.ContextLength == 0 {
+			m.ContextLength = m.MaxContextLength
+		}
+		m.SupportedInputModalities = remote.InputModalities
+		m.Thinking = nil
+		if len(remote.Reasoning) > 0 {
+			m.Thinking = &registry.ThinkingSupport{}
+			for _, level := range remote.Reasoning {
+				if level.Effort != "" {
+					m.Thinking.Levels = append(m.Thinking.Levels, level.Effort)
+				}
+			}
+		}
+		models = append(models, &m)
+	}
+	trace.Models(len(models))
+	reason := modeldiscovery.NoReason
+	if len(models) == 0 {
+		reason = modeldiscovery.EmptyCatalog
+	}
+	trace.End(modeldiscovery.Completed, reason)
+	return models, nil
+}
+
+func codexModelDiscoveryVersion(auth *cliproxyauth.Auth) (string, error) {
+	version, _ := auth.Metadata["hiroute_client_version"].(string)
+	refreshToken, _ := auth.Metadata["refresh_token"].(string)
+	if strings.TrimSpace(refreshToken) != "" {
+		// Independently authorized credentials belong to CPA. Advertise the same
+		// upstream client version its executor actually uses, including at the
+		// first OAuth registration before HiRoute has patched account controls.
+		// Access-only native leases must still provide their observed version.
+		clientIdentity, _, _ := strings.Cut(codexUserAgent, " ")
+		var ok bool
+		version, ok = strings.CutPrefix(clientIdentity, codexOriginator+"/")
+		if !ok {
+			return "", fmt.Errorf("codex model discovery: executor client version unavailable")
+		}
+	}
+	version = strings.TrimSpace(version)
+	if version == "" || len(version) > 128 || strings.ContainsAny(version, "\r\n\x00") {
+		return "", fmt.Errorf("codex model discovery: local client version unavailable")
+	}
+	return version, nil
+}
diff --git a/internal/runtime/executor/codex_models_test.go b/internal/runtime/executor/codex_models_test.go
new file mode 100644
index 0000000..c262d05
--- /dev/null
+++ b/internal/runtime/executor/codex_models_test.go
@@ -0,0 +1,84 @@
+package executor
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	cliproxyauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
+)
+
+type discoveryRoundTrip func(*http.Request) (*http.Response, error)
+
+func (f discoveryRoundTrip) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }
+
+func TestCodexModelDiscoveryFailureBounds(t *testing.T) {
+	a := &cliproxyauth.Auth{Metadata: map[string]any{"access_token": "secret", "hiroute_client_version": "0.999.0"}}
+	for _, tc := range []struct {
+		name     string
+		status   int
+		body     string
+		redirect bool
+	}{
+		{"redirect", 302, "", true},
+		{"oversized", 200, strings.Repeat("x", (16<<20)+1), false},
+		{"duplicate", 200, `{"models":[{"slug":"m"},{"slug":"m"}]}`, false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			calls := 0
+			ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", discoveryRoundTrip(func(r *http.Request) (*http.Response, error) {
+				calls++
+				h := make(http.Header)
+				if tc.redirect {
+					h.Set("Location", "https://example.com/stolen")
+				}
+				return &http.Response{StatusCode: tc.status, Header: h, Body: io.NopCloser(strings.NewReader(tc.body)), Request: r}, nil
+			}))
+			_, err := NewCodexExecutor(nil).DiscoverModels(ctx, a, nil)
+			if err == nil || calls != 1 || strings.Contains(err.Error(), "secret") {
+				t.Fatalf("unsafe failure handling: calls=%d err=%v", calls, err)
+			}
+		})
+	}
+}
+
+func TestCodexModelDiscoveryRequiresObservedVersion(t *testing.T) {
+	ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", discoveryRoundTrip(func(r *http.Request) (*http.Response, error) {
+		t.Fatal("must not query with an invented version")
+		return nil, nil
+	}))
+	for _, refresh := range []any{nil, "", "  "} {
+		_, err := NewCodexExecutor(nil).DiscoverModels(ctx, &cliproxyauth.Auth{Metadata: map[string]any{"access_token": "secret", "refresh_token": refresh}}, nil)
+		if err == nil || !strings.Contains(err.Error(), "local client version unavailable") {
+			t.Fatalf("missing version: %v", err)
+		}
+	}
+}
+
+func TestCodexModelDiscoveryManagedUsesExecutorVersion(t *testing.T) {
+	for _, observedVersion := range []any{nil, "0.999.0"} {
+		auth := &cliproxyauth.Auth{Provider: "codex", Metadata: map[string]any{
+			"access_token": "fixture-access", "refresh_token": "independent-refresh",
+			"account_id": "fixture-account", "hiroute_client_version": observedVersion,
+		}}
+		calls := 0
+		ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", discoveryRoundTrip(func(req *http.Request) (*http.Response, error) {
+			calls++
+			identity, _, _ := strings.Cut(req.Header.Get("User-Agent"), " ")
+			_, actualVersion, hasVersion := strings.Cut(identity, "/")
+			if !hasVersion || actualVersion == "" || req.URL.Query().Get("client_version") != actualVersion {
+				t.Fatal("managed discovery version differs from executor wire identity")
+			}
+			if req.URL.Query().Get("client_version") == "0.999.0" || req.Header.Get("Authorization") != "Bearer fixture-access" || req.Header.Get("ChatGPT-Account-ID") != "fixture-account" {
+				t.Fatal("managed discovery did not use its own credential and executor identity")
+			}
+			return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(`{"models":[{"slug":"remote-managed-model"}]}`)), Request: req}, nil
+		}))
+		models, err := NewCodexExecutor(nil).DiscoverModels(ctx, auth, nil)
+		if err != nil || calls != 1 || len(models) != 1 || models[0].ID != "remote-managed-model" {
+			t.Fatalf("independent login discovery failed: calls=%d models=%d err=%v", calls, len(models), err)
+		}
+	}
+}
diff --git a/internal/runtime/executor/helps/environment_proxy.go b/internal/runtime/executor/helps/environment_proxy.go
new file mode 100644
index 0000000..32f01f4
--- /dev/null
+++ b/internal/runtime/executor/helps/environment_proxy.go
@@ -0,0 +1,31 @@
+package helps
+
+import (
+	"errors"
+	"github.com/router-for-me/CLIProxyAPI/v8/sdk/proxyutil"
+	"net/http"
+	"net/url"
+)
+
+// Preserve provider TLS fingerprints while applying the standard environment
+// proxy and NO_PROXY rules to the actual destination. Selection errors fail closed.
+type environmentProxyTransport struct {
+	direct http.RoundTripper
+	build  func(string) http.RoundTripper
+	proxy  func(*http.Request) (*url.URL, error)
+}
+
+func (t *environmentProxyTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	proxy, err := t.proxy(req)
+	if err != nil {
+		return nil, err
+	}
+	if proxy == nil {
+		return t.direct.RoundTrip(req)
+	}
+	// CPA's transport constructor otherwise falls back to direct on invalid input.
+	if !proxyutil.ValidRequestProxy(proxy.String()) {
+		return nil, errors.New("invalid environment proxy")
+	}
+	return t.build(proxy.String()).RoundTrip(req)
+}
diff --git a/internal/runtime/executor/helps/environment_proxy_test.go b/internal/runtime/executor/helps/environment_proxy_test.go
new file mode 100644
index 0000000..8b7ef41
--- /dev/null
+++ b/internal/runtime/executor/helps/environment_proxy_test.go
@@ -0,0 +1,147 @@
+package helps
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+type environmentTestRT func(*http.Request) (*http.Response, error)
+
+func (f environmentTestRT) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }
+
+func TestEnvironmentProxySelection(t *testing.T) {
+	if os.Getenv("HIROUTE_PROXY_TEST_CHILD") == "1" {
+		c := NewUtlsHTTPClient(context.Background(), nil, nil, 0)
+		rt, ok := c.Transport.(*fallbackRoundTripper).chrome.(*environmentProxyTransport)
+		if !ok {
+			t.Fatal("protected transport ignores environment")
+		}
+		req, _ := http.NewRequest("GET", "https://chatgpt.com/backend-api/codex/models", nil)
+		p, err := rt.proxy(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		want := os.Getenv("HIROUTE_EXPECT_PROXY")
+		if want == "" {
+			if p != nil {
+				t.Fatal("NO_PROXY bypass lost")
+			}
+		} else if p == nil || p.String() != want {
+			t.Fatal("HTTPS proxy lost")
+		}
+		return
+	}
+	for _, bypass := range []bool{false, true} {
+		cmd := exec.Command(os.Args[0], "-test.run=^TestEnvironmentProxySelection$")
+		cmd.Env = []string{"HIROUTE_PROXY_TEST_CHILD=1", "HTTPS_PROXY=http://127.0.0.1:1187"}
+		if bypass {
+			cmd.Env = append(cmd.Env, "NO_PROXY=chatgpt.com")
+		} else {
+			cmd.Env = append(cmd.Env, "HIROUTE_EXPECT_PROXY=http://127.0.0.1:1187")
+		}
+		if out, err := cmd.CombinedOutput(); err != nil {
+			t.Fatalf("child: %v %s", err, out)
+		}
+	}
+}
+
+func TestEnvironmentProxyTransportNeverFallsBackOnError(t *testing.T) {
+	req, _ := http.NewRequest("GET", "https://chatgpt.com/", nil)
+	sentinel := errors.New("proxy failure")
+	directCalls := 0
+	rt := &environmentProxyTransport{
+		direct: environmentTestRT(func(*http.Request) (*http.Response, error) {
+			directCalls++
+			return &http.Response{StatusCode: 200}, nil
+		}),
+		proxy: func(*http.Request) (*url.URL, error) { return url.Parse("http://127.0.0.1:1187") },
+		build: func(s string) http.RoundTripper {
+			return environmentTestRT(func(*http.Request) (*http.Response, error) { return nil, sentinel })
+		},
+	}
+	if _, err := rt.RoundTrip(req); err != sentinel || directCalls != 0 {
+		t.Fatal("proxy failure fell back to direct")
+	}
+	rt.proxy = func(*http.Request) (*url.URL, error) { return nil, sentinel }
+	if _, err := rt.RoundTrip(req); err != sentinel || directCalls != 0 {
+		t.Fatal("selection failure fell back to direct")
+	}
+	rt.proxy = func(*http.Request) (*url.URL, error) { return nil, nil }
+	if _, err := rt.RoundTrip(req); err != nil || directCalls != 1 {
+		t.Fatal("direct bypass broken")
+	}
+}
+
+func TestInvalidEnvironmentProxyFailsBeforeTransportConstruction(t *testing.T) {
+	req, _ := http.NewRequest("GET", "https://chatgpt.com/", nil)
+	for _, raw := range []string{"ftp://127.0.0.1:1187", "http://127.0.0.1:0", "http://127.0.0.1:99999"} {
+		rt := &environmentProxyTransport{
+			proxy: func(*http.Request) (*url.URL, error) { return url.Parse(raw) },
+			build: func(string) http.RoundTripper { t.Fatal("invalid proxy reached constructor"); return nil },
+		}
+		if _, err := rt.RoundTrip(req); err == nil {
+			t.Fatal("invalid proxy accepted")
+		}
+	}
+}
+
+func TestHiRouteInferenceMalformedEnvironmentNeverDialsDirect(t *testing.T) {
+	if scenario := os.Getenv("HIROUTE_INFERENCE_BAD_PROXY_CASE"); scenario != "" {
+		key := "HTTPS_PROXY"
+		if scenario == "lower" {
+			key = "https_proxy"
+		}
+		t.Setenv(key, "http://%zz")
+		if scenario == "no-proxy" {
+			t.Setenv("NO_PROXY", "*")
+		}
+		if scenario == "upper-wins" {
+			t.Setenv("https_proxy", "http://127.0.0.1:1187")
+		}
+		client := NewUtlsHTTPClient(context.Background(), nil, nil, 0)
+		fallback := client.Transport.(*fallbackRoundTripper)
+		for _, protected := range []struct {
+			transport http.RoundTripper
+			target    string
+		}{
+			{fallback.chrome, "https://chatgpt.com/backend-api/codex/models"},
+			{fallback.anthropic, "https://api.anthropic.com/v1/messages"},
+		} {
+			route := protected.transport.(*environmentProxyTransport)
+			directCalls, proxyCalls := 0, 0
+			route.direct = environmentTestRT(func(*http.Request) (*http.Response, error) {
+				directCalls++
+				return &http.Response{StatusCode: http.StatusOK, Body: io.NopCloser(strings.NewReader(""))}, nil
+			})
+			route.build = func(string) http.RoundTripper {
+				proxyCalls++
+				return route.direct
+			}
+			request, _ := http.NewRequest(http.MethodPost, protected.target, nil)
+			response, err := client.Do(request)
+			if response != nil {
+				_ = response.Body.Close()
+			}
+			if err == nil || directCalls != 0 || proxyCalls != 0 {
+				t.Fatal("malformed effective proxy reached an inference transport")
+			}
+		}
+		return
+	}
+	for _, scenario := range []string{"upper", "lower", "no-proxy", "upper-wins"} {
+		t.Run(scenario, func(t *testing.T) {
+			command := exec.Command(os.Args[0], "-test.run=^TestHiRouteInferenceMalformedEnvironmentNeverDialsDirect$")
+			command.Env = []string{"HIROUTE_INFERENCE_BAD_PROXY_CASE=" + scenario}
+			if output, err := command.CombinedOutput(); err != nil {
+				t.Fatalf("isolated inference proxy case failed: %v\n%s", err, output)
+			}
+		})
+	}
+}
diff --git a/internal/runtime/executor/helps/hiroute_execution_test.go b/internal/runtime/executor/helps/hiroute_execution_test.go
new file mode 100644
index 0000000..09fe73b
--- /dev/null
+++ b/internal/runtime/executor/helps/hiroute_execution_test.go
@@ -0,0 +1,53 @@
+package helps
+
+import (
+	"context"
+	coreexecutor "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/executor"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+)
+
+func TestHiRouteExecutionCountsActualHTTPAndExcludesOAuth(t *testing.T) {
+	var sends atomic.Int32
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		n := sends.Add(1)
+		if r.URL.Path == "/oauth/token" {
+			w.WriteHeader(200)
+			return
+		}
+		if n == 1 {
+			w.WriteHeader(401)
+			return
+		}
+		w.WriteHeader(200)
+	}))
+	defer server.Close()
+	ctx, trace := coreexecutor.WithHiRouteExecution(context.Background())
+	reporter := NewUsageReporter(ctx, "codex", "fixture-model", nil)
+	client := reporter.TrackHTTPClient(server.Client())
+	for _, path := range []string{"/responses", "/oauth/token", "/responses"} {
+		// Auth manager replaces its per-executor tracker, but retains the trace.
+		child := coreexecutor.WithUpstreamAttemptTracker(ctx)
+		req, err := http.NewRequestWithContext(child, http.MethodPost, server.URL+path, nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+		coreexecutor.MarkUpstreamAttempt(child) // Claude's outer send marker.
+		selected := client
+		if path == "/oauth/token" {
+			selected = server.Client()
+		}
+		resp, err := selected.Do(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		_, _ = io.Copy(io.Discard, resp.Body)
+		_ = resp.Body.Close()
+	}
+	if sends.Load() != 3 || trace.Header() != "v1;2;1;0;0" {
+		t.Fatalf("actual HTTP=%d trace=%q", sends.Load(), trace.Header())
+	}
+}
diff --git a/internal/runtime/executor/helps/usage_helpers.go b/internal/runtime/executor/helps/usage_helpers.go
index 266012a..ef002b8 100644
--- a/internal/runtime/executor/helps/usage_helpers.go
+++ b/internal/runtime/executor/helps/usage_helpers.go
@@ -738,9 +738,16 @@ type usageTTFTRoundTripper struct {
 }
 
 func (t usageTTFTRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
+	if errCtx := req.Context().Err(); errCtx != nil {
+		return nil, errCtx
+	}
 	cliproxyexecutor.MarkUpstreamAttempt(req.Context())
+	cliproxyexecutor.HiRouteInferenceStarted(req.Context())
 	t.reporter.StartResponseTTFT()
 	resp, errRoundTrip := t.base.RoundTrip(req)
+	if resp != nil {
+		cliproxyexecutor.HiRouteInferenceResponse(req.Context(), resp.StatusCode)
+	}
 	if errRoundTrip != nil {
 		return resp, errRoundTrip
 	}
diff --git a/internal/runtime/executor/helps/utls_client.go b/internal/runtime/executor/helps/utls_client.go
index 4857bac..7247b85 100644
--- a/internal/runtime/executor/helps/utls_client.go
+++ b/internal/runtime/executor/helps/utls_client.go
@@ -385,6 +385,10 @@ func NewUtlsHTTPClient(ctx context.Context, cfg *config.Config, auth *cliproxyau
 		chromeRT = ctxRoundTripper
 		anthropicRT = ctxRoundTripper
 		standardTransport = ctxRoundTripper
+	} else {
+		selectProxy := proxyutil.EnvironmentProxyFunc()
+		chromeRT = &environmentProxyTransport{direct: chromeRT, build: func(proxy string) http.RoundTripper { return newUtlsRoundTripper(proxy) }, proxy: selectProxy}
+		anthropicRT = &environmentProxyTransport{direct: anthropicRT, build: cachedClaudeCodeRoundTripper, proxy: selectProxy}
 	}
 
 	client := &http.Client{
diff --git a/sdk/api/handlers/handlers.go b/sdk/api/handlers/handlers.go
index b4fc423..6b88bf3 100644
--- a/sdk/api/handlers/handlers.go
+++ b/sdk/api/handlers/handlers.go
@@ -539,6 +539,7 @@ func (h *BaseAPIHandler) GetContextWithCancel(handler interfaces.APIHandler, c *
 	}
 	newCtx = context.WithValue(newCtx, "gin", c)
 	newCtx = context.WithValue(newCtx, "handler", handler)
+	newCtx = withHiRouteExecution(newCtx, c)
 	return newCtx, func(params ...interface{}) {
 		if c != nil {
 			logging.SetResponseStatus(cancelCtx, c.Writer.Status())
diff --git a/sdk/api/handlers/header_filter.go b/sdk/api/handlers/header_filter.go
index e724674..4889c35 100644
--- a/sdk/api/handlers/header_filter.go
+++ b/sdk/api/handlers/header_filter.go
@@ -44,6 +44,7 @@ var cpaReservedResponseHeaders = map[string]struct{}{
 	"Access-Control-Expose-Headers":    {},
 	"Access-Control-Max-Age":           {},
 	"X-Cpa-Trace-Id":                   {},
+	"X-Hiroute-Cpa-Execution":          {},
 }
 
 // IsCPAReservedResponseHeader reports whether a downstream response header is managed by CPA.
diff --git a/sdk/api/handlers/hiroute_execution.go b/sdk/api/handlers/hiroute_execution.go
new file mode 100644
index 0000000..15168d3
--- /dev/null
+++ b/sdk/api/handlers/hiroute_execution.go
@@ -0,0 +1,53 @@
+package handlers
+
+import (
+	"context"
+	"github.com/gin-gonic/gin"
+	coreexecutor "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/executor"
+)
+
+// Snapshot immediately before the first downstream commit, including error
+// replies. Upstream/plugin headers cannot forge this reserved value. All stock
+// auth recovery finishes before a stream becomes visible to the downstream.
+func withHiRouteExecution(ctx context.Context, c *gin.Context) context.Context {
+	if c == nil || c.Writer == nil {
+		return ctx
+	}
+	if writer, ok := c.Writer.(*hiRouteExecutionWriter); ok {
+		return writer.trace.Context(ctx)
+	}
+	tracked, trace := coreexecutor.WithHiRouteExecution(ctx)
+	c.Writer = &hiRouteExecutionWriter{ResponseWriter: c.Writer, trace: trace}
+	return tracked
+}
+
+type hiRouteExecutionWriter struct {
+	gin.ResponseWriter
+	trace *coreexecutor.HiRouteExecution
+}
+
+func (w *hiRouteExecutionWriter) snapshot() {
+	if !w.Written() {
+		w.Header().Set(coreexecutor.HiRouteExecutionHeader, w.trace.Header())
+	}
+}
+func (w *hiRouteExecutionWriter) WriteHeader(code int) {
+	w.snapshot()
+	w.ResponseWriter.WriteHeader(code)
+}
+func (w *hiRouteExecutionWriter) WriteHeaderNow() {
+	w.snapshot()
+	w.ResponseWriter.WriteHeaderNow()
+}
+func (w *hiRouteExecutionWriter) Write(data []byte) (int, error) {
+	w.snapshot()
+	return w.ResponseWriter.Write(data)
+}
+func (w *hiRouteExecutionWriter) WriteString(data string) (int, error) {
+	w.snapshot()
+	return w.ResponseWriter.WriteString(data)
+}
+func (w *hiRouteExecutionWriter) Flush() {
+	w.snapshot()
+	w.ResponseWriter.Flush()
+}
diff --git a/sdk/api/handlers/hiroute_execution_test.go b/sdk/api/handlers/hiroute_execution_test.go
new file mode 100644
index 0000000..d052313
--- /dev/null
+++ b/sdk/api/handlers/hiroute_execution_test.go
@@ -0,0 +1,62 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"github.com/gin-gonic/gin"
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/interfaces"
+	coreexecutor "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/executor"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestHiRouteExecutionHeaderIncludesFailuresAndRejectsUpstreamSpoof(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	for _, status := range []int{200, 401, 404, 503} {
+		recorder := httptest.NewRecorder()
+		c, _ := gin.CreateTestContext(recorder)
+		c.Request = httptest.NewRequest(http.MethodPost, "/v1/responses", nil)
+		ctx := withHiRouteExecution(context.Background(), c)
+		coreexecutor.HiRouteInferenceStarted(ctx)
+		coreexecutor.HiRouteInferenceResponse(ctx, status)
+		c.Writer.Header().Set(coreexecutor.HiRouteExecutionHeader, "untrusted-provider-text")
+		if status == 200 {
+			c.Writer.WriteHeader(status)
+			_, _ = c.Writer.Write([]byte("{}"))
+		} else {
+			NewBaseAPIHandlers(nil, nil).WriteErrorResponse(c, &interfaces.ErrorMessage{
+				StatusCode: status, Error: errors.New("fixture error"),
+			})
+		}
+		expected := "v1;1;0;0;0"
+		if status == 401 {
+			expected = "v1;1;1;0;0"
+		}
+		if got := recorder.Result().Header.Get(coreexecutor.HiRouteExecutionHeader); got != expected {
+			t.Fatalf("status=%d trace=%q, want %q", status, got, expected)
+		}
+		if got := FilterUpstreamHeaders(http.Header{coreexecutor.HiRouteExecutionHeader: {"v1;32;0;0;0"}}); len(got) != 0 {
+			t.Fatalf("reserved header passed upstream filter: %v", got)
+		}
+	}
+}
+
+func TestHiRouteExecutionHeaderFreezesAtStreamCommit(t *testing.T) {
+	recorder := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(recorder)
+	c.Request = httptest.NewRequest(http.MethodPost, "/v1/messages", nil)
+	ctx := withHiRouteExecution(context.Background(), c)
+	coreexecutor.HiRouteInferenceStarted(ctx)
+	coreexecutor.HiRouteInferenceResponse(ctx, 401)
+	coreexecutor.HiRouteAuthRecovery(ctx, false)
+	coreexecutor.HiRouteAuthRecovery(ctx, true)
+	coreexecutor.HiRouteInferenceStarted(ctx)
+	_, _ = c.Writer.WriteString("data: {}\n\n")
+	c.Writer.Flush()
+	coreexecutor.HiRouteInferenceStarted(ctx)
+	_, _ = c.Writer.WriteString("data: [DONE]\n\n")
+	if got := recorder.Result().Header.Get(coreexecutor.HiRouteExecutionHeader); got != "v1;2;1;1;1" {
+		t.Fatalf("stream commit trace=%q", got)
+	}
+}
diff --git a/sdk/cliproxy/auth/conductor_refresh.go b/sdk/cliproxy/auth/conductor_refresh.go
index 4bf7fd1..18e48c6 100644
--- a/sdk/cliproxy/auth/conductor_refresh.go
+++ b/sdk/cliproxy/auth/conductor_refresh.go
@@ -485,12 +485,14 @@ func (m *Manager) tryRefreshAfterUnauthorized(ctx context.Context, auth *Auth, e
 	if !isUnauthorizedError(execErr) || !authHasRefreshCredential(auth) {
 		return auth, false
 	}
+	cliproxyexecutor.HiRouteAuthRecovery(ctx, false)
 	log.Debugf("unauthorized response for %s (%s), refreshing credentials before fallback", auth.Provider, auth.ID)
 	refreshed, errRefresh := m.refreshAuthForRequest(ctx, auth.ID, authAccessToken(auth))
 	if errRefresh != nil || refreshed == nil {
 		log.Debugf("credential refresh before fallback failed for %s (%s): %v", auth.Provider, auth.ID, errRefresh)
 		return auth, false
 	}
+	cliproxyexecutor.HiRouteAuthRecovery(ctx, true)
 	return refreshed, true
 }
 
@@ -537,6 +539,11 @@ func (m *Manager) refreshAuthForRequest(ctx context.Context, id, failedAccessTok
 	}
 	lock.mu.Lock()
 	defer lock.mu.Unlock()
+	// A canceled waiter must not refresh or persist credentials after another
+	// request releases the per-account refresh lock.
+	if errCtx := ctx.Err(); errCtx != nil {
+		return nil, errCtx
+	}
 
 	m.mu.RLock()
 	auth := m.auths[id]
diff --git a/sdk/cliproxy/auth/hiroute_execution_test.go b/sdk/cliproxy/auth/hiroute_execution_test.go
new file mode 100644
index 0000000..4b729b4
--- /dev/null
+++ b/sdk/cliproxy/auth/hiroute_execution_test.go
@@ -0,0 +1,118 @@
+package auth
+
+import (
+	"context"
+	"errors"
+	coreexecutor "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/executor"
+	"net/http"
+	"testing"
+)
+
+func TestHiRouteExecutionRecoveryUsesPinnedAuthAndCannotLoop(t *testing.T) {
+	for _, stream := range []bool{false, true} {
+		for _, mode := range []string{"managed", "borrowed", "invalid_after_refresh"} {
+			t.Run(mode, func(t *testing.T) {
+				m, executor, primary, _, model := newUnauthorizedRefreshFixture(t, false)
+				m.SetRetryConfig(0, 0, 1)
+				if mode == "borrowed" {
+					delete(primary.Metadata, "refresh_token")
+					if _, err := m.Update(context.Background(), primary); err != nil {
+						t.Fatal(err)
+					}
+				}
+				if mode == "invalid_after_refresh" {
+					executor.refreshTokens[primary.ID] = "still-invalid-token"
+					executor.tokenInvalid["still-invalid-token"] = struct{}{}
+				}
+				ctx, trace := coreexecutor.WithHiRouteExecution(context.Background())
+				opts := coreexecutor.Options{Metadata: map[string]any{coreexecutor.PinnedAuthMetadataKey: primary.ID}}
+				var err error
+				if stream {
+					result, errStream := m.ExecuteStream(ctx, []string{"codex"}, coreexecutor.Request{Model: model}, opts)
+					err = errStream
+					if result != nil {
+						for range result.Chunks {
+						}
+					}
+				} else {
+					_, err = m.Execute(ctx, []string{"codex"}, coreexecutor.Request{Model: model}, opts)
+				}
+				if (err == nil) != (mode == "managed") {
+					t.Fatalf("stream=%t mode=%s err=%v", stream, mode, err)
+				}
+				calls := executor.ExecuteCalls()
+				if stream {
+					calls = executor.StreamCalls()
+				}
+				wantCalls, wantRefresh, wantTrace := 2, 1, "v1;0;0;1;1"
+				if mode == "borrowed" {
+					wantCalls, wantRefresh, wantTrace = 1, 0, "v1;0;0;0;0"
+				}
+				if len(calls) != wantCalls || executor.RefreshCalls() != wantRefresh || trace.Header() != wantTrace {
+					t.Fatalf("stream=%t calls=%v refresh=%d trace=%q", stream, calls, executor.RefreshCalls(), trace.Header())
+				}
+				for _, id := range calls {
+					if id != primary.ID {
+						t.Fatalf("cross-account execution %q", id)
+					}
+				}
+				// This fixture has no HTTP transport. Do not invent wire counts.
+			})
+		}
+	}
+}
+
+func TestHiRouteCanceledRefreshWaiterDoesNotRefresh(t *testing.T) {
+	m, executor, primary, _, _ := newUnauthorizedRefreshFixture(t, false)
+	lock := &authRefreshLock{}
+	lock.mu.Lock()
+	m.refreshLocks.Store(primary.ID, lock)
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { _, err := m.refreshAuthForRequest(ctx, primary.ID, "stale-access-token"); done <- err }()
+	cancel()
+	lock.mu.Unlock()
+	if err := <-done; !errors.Is(err, context.Canceled) {
+		t.Fatalf("refresh error=%v", err)
+	}
+	if got := executor.RefreshCalls(); got != 0 {
+		t.Fatalf("canceled refresh calls=%d", got)
+	}
+}
+
+type hiRouteCommittedStreamExecutor struct{ *unauthorizedRefreshExecutor }
+
+func (e *hiRouteCommittedStreamExecutor) ExecuteStream(_ context.Context, auth *Auth, _ coreexecutor.Request, _ coreexecutor.Options) (*coreexecutor.StreamResult, error) {
+	e.mu.Lock()
+	e.streamCalls = append(e.streamCalls, auth.ID)
+	e.mu.Unlock()
+	chunks := make(chan coreexecutor.StreamChunk, 2)
+	chunks <- coreexecutor.StreamChunk{Payload: []byte("data: accepted\n\n")}
+	chunks <- coreexecutor.StreamChunk{Err: &Error{HTTPStatus: http.StatusUnauthorized, Message: "fixture stream failure"}}
+	close(chunks)
+	return &coreexecutor.StreamResult{Headers: http.Header{}, Chunks: chunks}, nil
+}
+
+func TestHiRouteStreamAfterPayloadCannotRefreshOrReplay(t *testing.T) {
+	m, executor, primary, _, model := newUnauthorizedRefreshFixture(t, false)
+	m.SetRetryConfig(0, 0, 1)
+	m.RegisterExecutor(&hiRouteCommittedStreamExecutor{executor})
+	ctx, trace := coreexecutor.WithHiRouteExecution(context.Background())
+	result, err := m.ExecuteStream(ctx, []string{"codex"}, coreexecutor.Request{Model: model},
+		coreexecutor.Options{Metadata: map[string]any{coreexecutor.PinnedAuthMetadataKey: primary.ID}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	payloads, failures := 0, 0
+	for chunk := range result.Chunks {
+		if len(chunk.Payload) != 0 {
+			payloads++
+		}
+		if chunk.Err != nil {
+			failures++
+		}
+	}
+	if payloads != 1 || failures != 1 || len(executor.StreamCalls()) != 1 || executor.RefreshCalls() != 0 || trace.Header() != "v1;0;0;0;0" {
+		t.Fatalf("payloads=%d failures=%d calls=%v refresh=%d trace=%s", payloads, failures, executor.StreamCalls(), executor.RefreshCalls(), trace.Header())
+	}
+}
diff --git a/sdk/cliproxy/executor/hiroute_execution.go b/sdk/cliproxy/executor/hiroute_execution.go
new file mode 100644
index 0000000..f896ccb
--- /dev/null
+++ b/sdk/cliproxy/executor/hiroute_execution.go
@@ -0,0 +1,104 @@
+package executor
+
+import (
+	"context"
+	"fmt"
+	"sync"
+)
+
+// HiRouteExecutionHeader is a package-private bridge contract. It contains only
+// bounded counts, never account identifiers, credentials, usage or provider text.
+const HiRouteExecutionHeader = "X-Hiroute-Cpa-Execution"
+
+type hiRouteExecutionKey struct{}
+
+type HiRouteExecution struct {
+	mu                    sync.Mutex
+	inferenceAttempts     uint32
+	unauthorizedResponses uint32
+	authRecoveryAttempts  uint32
+	authRecoverySuccesses uint32
+	overflow              bool
+}
+
+// WithHiRouteExecution owns one downstream HTTP call across auth-manager child
+// contexts. OAuth refresh and account discovery do not use the inference hook.
+func WithHiRouteExecution(ctx context.Context) (context.Context, *HiRouteExecution) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if value, ok := ctx.Value(hiRouteExecutionKey{}).(*HiRouteExecution); ok && value != nil {
+		return ctx, value
+	}
+	trace := &HiRouteExecution{}
+	return trace.Context(ctx), trace
+}
+
+// Context keeps a request's existing trace without replacing the new caller's
+// deadline or cancellation parent when a handler creates another child context.
+func (t *HiRouteExecution) Context(ctx context.Context) context.Context {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	return context.WithValue(ctx, hiRouteExecutionKey{}, t)
+}
+
+func hiRouteExecutionFrom(ctx context.Context) *HiRouteExecution {
+	if ctx == nil {
+		return nil
+	}
+	trace, _ := ctx.Value(hiRouteExecutionKey{}).(*HiRouteExecution)
+	return trace
+}
+
+func (t *HiRouteExecution) increment(value *uint32) {
+	// The wire contract never allocates per attempt. Exceeding this observation
+	// bound is explicit unknown, not a fabricated/clamped attempt count.
+	if *value >= 32 {
+		t.overflow = true
+		return
+	}
+	*value++
+}
+
+// HiRouteInferenceStarted is called at the actual HTTP RoundTrip boundary,
+// rather than MarkUpstreamAttempt, which can run more than once per wire send.
+func HiRouteInferenceStarted(ctx context.Context) {
+	if trace := hiRouteExecutionFrom(ctx); trace != nil {
+		trace.mu.Lock()
+		defer trace.mu.Unlock()
+		trace.increment(&trace.inferenceAttempts)
+	}
+}
+
+func HiRouteInferenceResponse(ctx context.Context, status int) {
+	if status != 401 {
+		return
+	}
+	if trace := hiRouteExecutionFrom(ctx); trace != nil {
+		trace.mu.Lock()
+		defer trace.mu.Unlock()
+		trace.increment(&trace.unauthorizedResponses)
+	}
+}
+
+func HiRouteAuthRecovery(ctx context.Context, success bool) {
+	if trace := hiRouteExecutionFrom(ctx); trace != nil {
+		trace.mu.Lock()
+		defer trace.mu.Unlock()
+		if success {
+			trace.increment(&trace.authRecoverySuccesses)
+		} else {
+			trace.increment(&trace.authRecoveryAttempts)
+		}
+	}
+}
+
+func (t *HiRouteExecution) Header() string {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	if t.overflow {
+		return "v1;unknown"
+	}
+	return fmt.Sprintf("v1;%d;%d;%d;%d", t.inferenceAttempts, t.unauthorizedResponses, t.authRecoveryAttempts, t.authRecoverySuccesses)
+}
diff --git a/sdk/cliproxy/executor/hiroute_execution_test.go b/sdk/cliproxy/executor/hiroute_execution_test.go
new file mode 100644
index 0000000..91db81d
--- /dev/null
+++ b/sdk/cliproxy/executor/hiroute_execution_test.go
@@ -0,0 +1,16 @@
+package executor
+
+import (
+	"context"
+	"testing"
+)
+
+func TestHiRouteExecutionOverflowIsUnknown(t *testing.T) {
+	ctx, trace := WithHiRouteExecution(context.Background())
+	for i := 0; i < 33; i++ {
+		HiRouteInferenceStarted(ctx)
+	}
+	if trace.Header() != "v1;unknown" {
+		t.Fatalf("overflow trace=%q", trace.Header())
+	}
+}
diff --git a/sdk/cliproxy/service_auth.go b/sdk/cliproxy/service_auth.go
index c2b4f73..035cda4 100644
--- a/sdk/cliproxy/service_auth.go
+++ b/sdk/cliproxy/service_auth.go
@@ -5,6 +5,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
 	"github.com/router-for-me/CLIProxyAPI/v8/internal/runtime/executor"
 	"github.com/router-for-me/CLIProxyAPI/v8/internal/util"
 	"github.com/router-for-me/CLIProxyAPI/v8/internal/watcher"
@@ -100,6 +101,11 @@ func (s *Service) handleAuthUpdates(ctx context.Context, updates []watcher.AuthU
 	if s == nil {
 		return
 	}
+	// Accepted updates are pending even while waiting for the update lock.
+	for _, update := range updates {
+		done := modeldiscovery.Registering(authUpdateID(update))
+		defer done()
+	}
 	// Keep this path limited to the targeted auths. Global plugin rebuilds and
 	// in-flight Antigravity probes can hold authUpdateMu for minutes and stall
 	// Management API PATCH responses.
diff --git a/sdk/cliproxy/service_codex_discovery_test.go b/sdk/cliproxy/service_codex_discovery_test.go
new file mode 100644
index 0000000..8909d5d
--- /dev/null
+++ b/sdk/cliproxy/service_codex_discovery_test.go
@@ -0,0 +1,114 @@
+package cliproxy
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
+	coreauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
+	"github.com/router-for-me/CLIProxyAPI/v8/sdk/config"
+)
+
+type discoveryTransport func(*http.Request) (*http.Response, error)
+
+func (f discoveryTransport) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }
+
+func TestCodexDiscoveryRegistration(t *testing.T) {
+	s := &Service{cfg: &config.Config{}}
+	s.cfg.ForceModelPrefix = true
+	a := &coreauth.Auth{ID: "discovery-account", Provider: "codex", Prefix: "subscription", Metadata: map[string]any{"access_token": "test-token", "account_id": "test-account", "hiroute_client_version": "0.999.0"}, Attributes: map[string]string{"excluded_models": "excluded"}}
+	defer GlobalModelRegistry().UnregisterClient(a.ID)
+	status, body := 200, `{"models":[{"slug":"future-model-not-in-bundle","display_name":"Future","context_window":123456,"input_modalities":["text","image"],"supported_reasoning_levels":[{"effort":"max"}]},{"slug":"excluded"}]}`
+	ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", discoveryTransport(func(r *http.Request) (*http.Response, error) {
+		if r.URL.String() != "https://chatgpt.com/backend-api/codex/models?client_version=0.999.0" || r.Header.Get("Authorization") != "Bearer test-token" || r.Header.Get("ChatGPT-Account-ID") != "test-account" {
+			t.Fatal("wrong discovery request")
+		}
+		if _, ok := r.Context().Deadline(); !ok {
+			t.Fatal("missing deadline")
+		}
+		return &http.Response{StatusCode: status, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(body)), Request: r}, nil
+	}))
+	s.registerModelsForAuth(ctx, a)
+	check := func() {
+		t.Helper()
+		models := GlobalModelRegistry().GetModelsForClient(a.ID)
+		if len(models) != 1 || models[0].ID != "subscription/future-model-not-in-bundle" || models[0].ContextLength != 123456 || models[0].Thinking.Levels[0] != "max" {
+			t.Fatalf("unexpected registered models: %+v", models)
+		}
+	}
+	check()
+	for _, failure := range []struct {
+		status int
+		body   string
+	}{{401, `secret upstream error`}, {200, `{broken`}, {200, `{}`}, {200, `{"models":[{"slug":""}]}`}} {
+		status, body = failure.status, failure.body
+		s.registerModelsForAuth(ctx, a)
+		check()
+	}
+	status, body = 200, `{"models":[]}`
+	s.registerModelsForAuth(ctx, a)
+	if len(GlobalModelRegistry().GetModelsForClient(a.ID)) != 0 {
+		t.Fatal("empty authoritative list did not remove models")
+	}
+	snapshot := modeldiscovery.Read(a.ID)
+	if snapshot.FirstFailure == nil || snapshot.FirstFailure.Reason != modeldiscovery.HTTPRejected || snapshot.Latest == nil || snapshot.Latest.Phase != modeldiscovery.Registration || snapshot.Latest.Reason != modeldiscovery.EmptyAfterFiltering {
+		t.Fatalf("lost first failure or empty registration facts: %+v", snapshot)
+	}
+	if snapshot.Latest.Timings[4].Reason != modeldiscovery.EmptyCatalog {
+		t.Fatal("upstream empty catalog was confused with filtering")
+	}
+	status, body = 200, `{"models":[{"slug":"other-account-model"}]}`
+	a.ID, a.Prefix = "other-account", "other"
+	defer GlobalModelRegistry().UnregisterClient(a.ID)
+	s.registerModelsForAuth(ctx, a)
+	if len(GlobalModelRegistry().GetModelsForClient("discovery-account")) != 0 {
+		t.Fatal("cross-account catalog leakage")
+	}
+}
+
+func TestHiRouteDiscoveryRegistrationDiscard(t *testing.T) {
+	for _, reason := range []modeldiscovery.Reason{modeldiscovery.AccountMissing, modeldiscovery.AccountDisabled, modeldiscovery.AccountChanged, modeldiscovery.Cancelled} {
+		t.Run(string(reason), func(t *testing.T) {
+			manager := coreauth.NewManager(nil, nil, nil)
+			a := &coreauth.Auth{ID: "discard-" + string(reason), Provider: "codex", Metadata: map[string]any{"access_token": "private-test-token", "hiroute_client_version": "0.999.0"}}
+			registered, err := manager.Register(context.Background(), a)
+			if err != nil {
+				t.Fatal(err)
+			}
+			a = registered.Clone()
+			s := &Service{cfg: &config.Config{}, coreManager: manager}
+			ctx, cancel := context.WithCancel(context.Background())
+			defer cancel()
+			ctx = context.WithValue(ctx, "cliproxy.roundtripper", discoveryTransport(func(r *http.Request) (*http.Response, error) {
+				switch reason {
+				case modeldiscovery.AccountMissing:
+					manager.Remove(context.Background(), a.ID)
+				case modeldiscovery.AccountDisabled, modeldiscovery.AccountChanged:
+					current, _ := manager.GetByID(a.ID)
+					current.Disabled = reason == modeldiscovery.AccountDisabled
+					current.RegistrationEpoch++
+					if _, err := manager.Update(context.Background(), current); err != nil {
+						t.Fatal(err)
+					}
+				case modeldiscovery.Cancelled:
+					cancel()
+				}
+				return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(`{"models":[{"slug":"safe-model"}]}`)), Request: r}, nil
+			}))
+			s.registerModelsForAuth(ctx, a)
+			snapshot := modeldiscovery.Read(a.ID)
+			if snapshot.Latest == nil || snapshot.Latest.Phase != modeldiscovery.Registration || snapshot.Latest.Outcome != modeldiscovery.Discarded || snapshot.Latest.Reason != reason {
+				t.Fatalf("wrong discard: %+v", snapshot.Latest)
+			}
+			if reason == modeldiscovery.AccountChanged && (snapshot.Latest.RegistrationEpochMatches == nil || *snapshot.Latest.RegistrationEpochMatches) {
+				t.Fatal("missing exact registration epoch mismatch")
+			}
+			if len(GlobalModelRegistry().GetModelsForClient(a.ID)) != 0 {
+				t.Fatal("discarded catalog registered")
+			}
+		})
+	}
+}
diff --git a/sdk/cliproxy/service_codex_registration.go b/sdk/cliproxy/service_codex_registration.go
new file mode 100644
index 0000000..518a73f
--- /dev/null
+++ b/sdk/cliproxy/service_codex_registration.go
@@ -0,0 +1,48 @@
+package cliproxy
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
+	coreauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
+)
+
+func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreauth.Auth, cache *openAICompatibilityRegistrationCache) {
+	if a != nil {
+		done := modeldiscovery.Registering(a.ID)
+		defer done()
+	}
+	if !codexDiscoveryAccount(a) {
+		s.registerModelsForAuthAttempt(ctx, a, cache)
+		return
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	// A newer generation may supersede a lookup while it is in flight. Discard
+	// its result, then discover once for that latest generation in the SAME
+	// five-second budget. Transport failures do not request a handoff.
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	if s != nil && s.coreManager != nil {
+		if latest, ok := s.coreManager.GetByID(a.ID); ok && latest != nil && latest.RegistrationEpoch == a.RegistrationEpoch && codexDiscoveryAccount(latest) {
+			a = latest
+		}
+	}
+	for attempt := 0; attempt < 2 && ctx.Err() == nil; attempt++ {
+		a = s.registerModelsForAuthAttempt(ctx, a, cache)
+		if a == nil {
+			return
+		}
+	}
+}
+
+func codexDiscoveryAccount(a *coreauth.Auth) bool {
+	if a == nil || !strings.EqualFold(strings.TrimSpace(a.Provider), "codex") || a.AuthKind() == "apikey" {
+		return false
+	}
+	token, _ := a.Metadata["access_token"].(string)
+	return strings.TrimSpace(token) != ""
+}
diff --git a/sdk/cliproxy/service_codex_registration_test.go b/sdk/cliproxy/service_codex_registration_test.go
new file mode 100644
index 0000000..63e93fc
--- /dev/null
+++ b/sdk/cliproxy/service_codex_registration_test.go
@@ -0,0 +1,208 @@
+package cliproxy
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/watcher"
+	coreauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
+	"github.com/router-for-me/CLIProxyAPI/v8/sdk/config"
+)
+
+func TestHiRouteCodexRegistrationUsesLatestGeneration(t *testing.T) {
+	manager := coreauth.NewManager(nil, nil, nil)
+	original, err := manager.Register(context.Background(), &coreauth.Auth{ID: "generation-handoff", Provider: "codex", Prefix: "old", Metadata: map[string]any{"access_token": "old-access", "hiroute_client_version": "0.999.0"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer GlobalModelRegistry().UnregisterClient(original.ID)
+	service := &Service{cfg: &config.Config{}, coreManager: manager}
+	service.cfg.ForceModelPrefix = true
+	calls := 0
+	var firstDeadline time.Time
+	ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", discoveryTransport(func(r *http.Request) (*http.Response, error) {
+		calls++
+		if !modeldiscovery.Read(original.ID).RegistrationPending {
+			t.Fatal("registration scope ended before its lookup/handoff")
+		}
+		deadline, ok := r.Context().Deadline()
+		if !ok {
+			t.Fatal("missing discovery bound")
+		}
+		body := `{"models":[{"slug":"old-only"}]}`
+		switch calls {
+		case 1:
+			firstDeadline = deadline
+			if r.Header.Get("Authorization") != "Bearer old-access" {
+				t.Fatal("wrong original credential")
+			}
+			next, _ := manager.GetByID(original.ID)
+			next.Prefix = "new"
+			next.Metadata["access_token"] = "new-access"
+			if _, err := manager.Update(context.Background(), next); err != nil {
+				t.Fatal(err)
+			}
+			time.Sleep(15 * time.Millisecond)
+		case 2:
+			if !deadline.Equal(firstDeadline) {
+				t.Fatal("handoff reset the discovery deadline")
+			}
+			if r.Header.Get("Authorization") != "Bearer new-access" {
+				t.Fatal("latest credential not used")
+			}
+			body = `{"models":[{"slug":"new-only"}]}`
+		default:
+			t.Fatal("unbounded generation handoff")
+		}
+		return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(body)), Request: r}, nil
+	}))
+	service.completeModelRegistrationForAuth(ctx, original)
+	models := GlobalModelRegistry().GetModelsForClient(original.ID)
+	if calls != 2 || len(models) != 1 || models[0].ID != "new/new-only" {
+		t.Fatalf("latest authorization lost: calls=%d models=%+v", calls, models)
+	}
+	snapshot := modeldiscovery.Read(original.ID)
+	if snapshot.RegistrationPending {
+		t.Fatal("registration scope leaked after completion")
+	}
+	if snapshot.FirstFailure == nil || snapshot.FirstFailure.Reason != modeldiscovery.AccountChanged || snapshot.Latest == nil || snapshot.Latest.Phase != modeldiscovery.Registration || snapshot.Latest.Outcome != modeldiscovery.Completed {
+		t.Fatal("handoff lost failure/recovery evidence")
+	}
+}
+
+func TestHiRouteCodexRegistrationHandoffIsBoundedAndDoesNotRetryTransport(t *testing.T) {
+	for _, mutate := range []bool{false, true} {
+		name := "transport"
+		if mutate {
+			name = "continuous-generation-change"
+		}
+		t.Run(name, func(t *testing.T) {
+			manager := coreauth.NewManager(nil, nil, nil)
+			original, err := manager.Register(context.Background(), &coreauth.Auth{ID: "bounded-" + name, Provider: "codex", Metadata: map[string]any{"access_token": "test-access", "hiroute_client_version": "0.999.0"}})
+			if err != nil {
+				t.Fatal(err)
+			}
+			service := &Service{cfg: &config.Config{}, coreManager: manager}
+			calls := 0
+			ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", discoveryTransport(func(r *http.Request) (*http.Response, error) {
+				calls++
+				if !mutate {
+					return nil, errors.New("synthetic transport failure")
+				}
+				if calls > 2 {
+					t.Fatal("unbounded registration handoff")
+				}
+				next, _ := manager.GetByID(original.ID)
+				if _, err := manager.Update(context.Background(), next); err != nil {
+					t.Fatal(err)
+				}
+				return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(`{"models":[{"slug":"stale"}]}`)), Request: r}, nil
+			}))
+			service.completeModelRegistrationForAuth(ctx, original)
+			expected := 1
+			if mutate {
+				expected = 2
+			}
+			if calls != expected || len(GlobalModelRegistry().GetModelsForClient(original.ID)) != 0 {
+				t.Fatalf("wrong bounded outcome: calls=%d", calls)
+			}
+		})
+	}
+}
+
+func TestHiRouteCodexRegistrationDoesNotFollowRevokedOrReplacedAccount(t *testing.T) {
+	for _, action := range []string{"removed", "disabled", "no-access", "replaced"} {
+		t.Run(action, func(t *testing.T) {
+			manager := coreauth.NewManager(nil, nil, nil)
+			original, err := manager.Register(context.Background(), &coreauth.Auth{ID: "revoke-" + action, Provider: "codex", Metadata: map[string]any{"access_token": "test-access", "hiroute_client_version": "0.999.0"}})
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer GlobalModelRegistry().UnregisterClient(original.ID)
+			service := &Service{cfg: &config.Config{}, coreManager: manager}
+			calls := 0
+			ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", discoveryTransport(func(r *http.Request) (*http.Response, error) {
+				calls++
+				current, _ := manager.GetByID(original.ID)
+				switch action {
+				case "removed":
+					manager.Remove(context.Background(), original.ID)
+				case "replaced":
+					manager.Remove(context.Background(), original.ID)
+					if _, err := manager.Register(context.Background(), current); err != nil {
+						t.Fatal(err)
+					}
+				default:
+					if action == "disabled" {
+						current.Disabled = true
+					} else {
+						delete(current.Metadata, "access_token")
+					}
+					if _, err := manager.Update(context.Background(), current); err != nil {
+						t.Fatal(err)
+					}
+				}
+				return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(`{"models":[{"slug":"stale"}]}`)), Request: r}, nil
+			}))
+			service.completeModelRegistrationForAuth(ctx, original)
+			if calls != 1 || len(GlobalModelRegistry().GetModelsForClient(original.ID)) != 0 {
+				t.Fatal("followed revoked/replaced authorization or introduced static fallback")
+			}
+		})
+	}
+}
+
+func TestHiRouteCodexRegistrationPendingIncludesQueuedWork(t *testing.T) {
+	manager := coreauth.NewManager(nil, nil, nil)
+	original, err := manager.Register(context.Background(), &coreauth.Auth{ID: "queued-registration", Provider: "codex", Prefix: "subscription", Metadata: map[string]any{"access_token": "synthetic-access", "hiroute_client_version": "0.999.0"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer GlobalModelRegistry().UnregisterClient(original.ID)
+	prior := modeldiscovery.Begin(original.ID)
+	prior.Enter(modeldiscovery.Request)
+	prior.End(modeldiscovery.Failed, modeldiscovery.Timeout)
+	next, _ := manager.GetByID(original.ID)
+	next, err = manager.Update(context.Background(), next)
+	if err != nil {
+		t.Fatal(err)
+	}
+	service := &Service{cfg: &config.Config{}, coreManager: manager}
+	service.cfg.ForceModelPrefix = true
+	ctx := context.WithValue(context.Background(), "cliproxy.roundtripper", discoveryTransport(func(r *http.Request) (*http.Response, error) {
+		return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(`{"models":[{"slug":"current-model"}]}`)), Request: r}, nil
+	}))
+	service.authUpdateMu.Lock()
+	started, finished := make(chan struct{}), make(chan struct{})
+	go func() {
+		defer close(finished)
+		close(started)
+		service.handleAuthUpdate(ctx, watcher.AuthUpdate{Action: watcher.AuthUpdateActionModify, ID: next.ID, Auth: next})
+	}()
+	<-started
+	deadline := time.Now().Add(time.Second)
+	for !modeldiscovery.Read(original.ID).RegistrationPending && time.Now().Before(deadline) {
+		time.Sleep(time.Millisecond)
+	}
+	var models []*ModelInfo
+	blocked := modeldiscovery.ReadCatalog(original.ID, func() { models = GlobalModelRegistry().GetModelsForClient(original.ID) })
+	service.authUpdateMu.Unlock()
+	select {
+	case <-finished:
+	case <-time.After(2 * time.Second):
+		t.Fatal("queued registration did not finish")
+	}
+	if len(models) != 0 || !blocked.RegistrationPending || blocked.Latest == nil || blocked.Latest.Outcome != modeldiscovery.Failed {
+		t.Fatal("accepted update waiting for the lock looked terminal")
+	}
+	recovered := GlobalModelRegistry().GetModelsForClient(original.ID)
+	if len(recovered) != 1 || recovered[0].ID != "subscription/current-model" || modeldiscovery.Read(original.ID).RegistrationPending {
+		t.Fatal("queued registration did not recover and clear pending state")
+	}
+}
diff --git a/sdk/cliproxy/service_models.go b/sdk/cliproxy/service_models.go
index 1bb4b62..107749c 100644
--- a/sdk/cliproxy/service_models.go
+++ b/sdk/cliproxy/service_models.go
@@ -8,9 +8,12 @@ import (
 
 	"github.com/router-for-me/CLIProxyAPI/v8/internal/constant"
 	"github.com/router-for-me/CLIProxyAPI/v8/internal/modelconfig"
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/modeldiscovery"
 	"github.com/router-for-me/CLIProxyAPI/v8/internal/registry"
+	"github.com/router-for-me/CLIProxyAPI/v8/internal/runtime/executor"
 	coreauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
 	"github.com/router-for-me/CLIProxyAPI/v8/sdk/config"
+	log "github.com/sirupsen/logrus"
 )
 
 // registerModelsForAuth (re)binds provider models in the global registry using the core auth ID as client identifier.
@@ -18,7 +21,7 @@ func (s *Service) registerModelsForAuth(ctx context.Context, a *coreauth.Auth) {
 	s.registerModelsForAuthWithCache(ctx, a, nil)
 }
 
-func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreauth.Auth, compatCache *openAICompatibilityRegistrationCache) {
+func (s *Service) registerModelsForAuthAttempt(ctx context.Context, a *coreauth.Auth, compatCache *openAICompatibilityRegistrationCache) (rebind *coreauth.Auth) {
 	if a == nil || a.ID == "" {
 		return
 	}
@@ -71,6 +74,7 @@ func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreaut
 		return
 	}
 	var models []*ModelInfo
+	var discoveryTrace *modeldiscovery.Trace
 	switch provider {
 	case constant.Gemini:
 		models = registry.GetGeminiModels()
@@ -149,6 +153,37 @@ func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreaut
 		default:
 			models = registry.GetCodexProModels()
 		}
+		if token, _ := a.Metadata["access_token"].(string); strings.TrimSpace(token) != "" {
+			discoveryTrace = modeldiscovery.Begin(a.ID)
+			discovered, err := executor.NewCodexExecutor(s.cfg).DiscoverModels(modeldiscovery.WithTrace(ctx, discoveryTrace), a, models)
+			if err != nil {
+				log.Warnf("Codex model discovery failed; retaining registered catalog: %v", err)
+				return
+			}
+			discoveryTrace.Enter(modeldiscovery.Registration)
+			// An auth removed or replaced during the bounded request must not reappear.
+			if s.coreManager != nil {
+				current, ok := s.coreManager.GetByID(a.ID)
+				if ok {
+					discoveryTrace.RegistrationChecks(current.Generation == a.Generation, current.RegistrationEpoch == a.RegistrationEpoch)
+				}
+				if !ok || current.Disabled || current.Generation != a.Generation || current.RegistrationEpoch != a.RegistrationEpoch {
+					reason := modeldiscovery.AccountChanged
+					if !ok {
+						reason = modeldiscovery.AccountMissing
+					} else if current.Disabled {
+						reason = modeldiscovery.AccountDisabled
+					}
+					discoveryTrace.End(modeldiscovery.Discarded, reason)
+					if ok && !current.Disabled && current.RegistrationEpoch == a.RegistrationEpoch && current.Generation != a.Generation && codexDiscoveryAccount(current) && ctx.Err() == nil {
+						return current
+					}
+					return
+				}
+			}
+			models = discovered
+			log.Infof("Codex account model discovery completed: %d models", len(models))
+		}
 		models = applyExcludedModels(models, excluded)
 	case "kimi", "kimi-ai", "kimi.ai", "kimi.com":
 		models = registry.GetKimiModels()
@@ -283,10 +318,16 @@ func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreaut
 		}
 	}
 	if ctx.Err() != nil {
+		if discoveryTrace != nil {
+			discoveryTrace.End(modeldiscovery.Discarded, modeldiscovery.Cancelled)
+		}
 		return
 	}
 	models = applyOAuthModelAliasForAuth(s.cfg, provider, authKind, a.Attributes, models)
 	if ctx.Err() != nil {
+		if discoveryTrace != nil {
+			discoveryTrace.End(modeldiscovery.Discarded, modeldiscovery.Cancelled)
+		}
 		return
 	}
 	key := provider
@@ -297,6 +338,15 @@ func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreaut
 	if len(models) > 0 {
 		models = applyOAuthSettingsForAuth(s.cfg, provider, authKind, models)
 		s.registerResolvedModelsForAuth(a, key, applyModelPrefixes(models, a.Prefix, s.cfg != nil && s.cfg.ForceModelPrefix))
+		if discoveryTrace != nil {
+			registered := GlobalModelRegistry().GetModelsForClient(a.ID)
+			discoveryTrace.Models(len(registered))
+			reason := modeldiscovery.NoReason
+			if len(registered) == 0 {
+				reason = modeldiscovery.EmptyAfterFiltering
+			}
+			discoveryTrace.End(modeldiscovery.Completed, reason)
+		}
 		if strings.EqualFold(strings.TrimSpace(a.Provider), "antigravity") {
 			s.asyncProbeAntigravityCapabilities(ctx, a, key)
 		}
@@ -304,6 +354,11 @@ func (s *Service) registerModelsForAuthWithCache(ctx context.Context, a *coreaut
 	}
 
 	GlobalModelRegistry().UnregisterClient(a.ID)
+	if discoveryTrace != nil {
+		discoveryTrace.Models(0)
+		discoveryTrace.End(modeldiscovery.Completed, modeldiscovery.EmptyAfterFiltering)
+	}
+	return
 }
 
 // refreshModelRegistrationForAuth re-applies the latest model registration for
@@ -325,6 +380,8 @@ func (s *Service) refreshModelRegistrationForAuthWithContext(ctx context.Context
 	if s == nil || s.coreManager == nil || current == nil || current.ID == "" {
 		return false
 	}
+	done := modeldiscovery.Registering(current.ID)
+	defer done()
 	if ctx == nil {
 		ctx = context.Background()
 	}
diff --git a/sdk/proxyutil/environment.go b/sdk/proxyutil/environment.go
new file mode 100644
index 0000000..46f700b
--- /dev/null
+++ b/sdk/proxyutil/environment.go
@@ -0,0 +1,52 @@
+package proxyutil
+
+import (
+	"errors"
+	"net/http"
+	"net/url"
+
+	"golang.org/x/net/http/httpproxy"
+)
+
+// EnvironmentProxyFunc captures the standard HTTP(S)_PROXY/NO_PROXY settings,
+// but rejects a malformed effective proxy instead of silently dialing directly.
+// Uppercase nonempty values win, host[:port] shorthand remains valid, and only
+// the request's scheme is validated. Invalid configuration fails even when a
+// NO_PROXY rule would otherwise bypass it; explicit direct mode does not call us.
+func EnvironmentProxyFunc() func(*http.Request) (*url.URL, error) {
+	cfg := httpproxy.FromEnvironment()
+	httpError := validateEnvironmentProxy(cfg.HTTPProxy)
+	httpsError := validateEnvironmentProxy(cfg.HTTPSProxy)
+	selectProxy := cfg.ProxyFunc()
+	return func(request *http.Request) (*url.URL, error) {
+		if request == nil || request.URL == nil {
+			return nil, errors.New("invalid environment proxy request")
+		}
+		switch request.URL.Scheme {
+		case "http":
+			if httpError != nil {
+				return nil, httpError
+			}
+		case "https":
+			if httpsError != nil {
+				return nil, httpsError
+			}
+		}
+		return selectProxy(request.URL)
+	}
+}
+
+func validateEnvironmentProxy(raw string) error {
+	if raw == "" {
+		return nil
+	}
+	parsed, err := url.Parse(raw)
+	if err != nil || parsed.Scheme == "" || parsed.Host == "" {
+		// Match Go's documented environment-only host[:port] shorthand.
+		parsed, err = url.Parse("http://" + raw)
+	}
+	if err != nil || !ValidRequestProxy(parsed.String()) {
+		return errors.New("invalid environment proxy configuration")
+	}
+	return nil
+}
diff --git a/sdk/proxyutil/proxy.go b/sdk/proxyutil/proxy.go
index 4119baa..8f6d675 100644
--- a/sdk/proxyutil/proxy.go
+++ b/sdk/proxyutil/proxy.go
@@ -20,6 +20,14 @@ import (
 // Mode describes how a proxy setting should be interpreted.
 type Mode int
 
+// ConnectStatusError preserves a machine-readable proxy status without carrying
+// its untrusted reason phrase into discovery diagnostics.
+type ConnectStatusError struct{ StatusCode int }
+
+func (e *ConnectStatusError) Error() string {
+	return fmt.Sprintf("proxy CONNECT returned status %d", e.StatusCode)
+}
+
 const (
 	// ModeInherit means no explicit proxy behavior was configured.
 	ModeInherit Mode = iota
@@ -312,10 +320,8 @@ func (d *httpConnectDialer) DialContext(ctx context.Context, network, addr strin
 		if resp.Body != nil {
 			_ = resp.Body.Close()
 		}
-		if errClose := conn.Close(); errClose != nil {
-			return nil, fmt.Errorf("proxy CONNECT returned status %s; close failed: %v", resp.Status, errClose)
-		}
-		return nil, fmt.Errorf("proxy CONNECT returned status %s", resp.Status)
+		_ = conn.Close()
+		return nil, &ConnectStatusError{StatusCode: resp.StatusCode}
 	}
 
 	if errContext := ctx.Err(); errContext != nil {