@bitkyc08/opencodex 2.75.0 → 2.76.0

package/src/router.ts

@@ -89,6 +89,12 @@ export interface RouteResult {
   combo?: ComboPick;
   /** Bounded route-decision trace (RI-01); never contains secrets. */
   routeDecision?: RouteDecisionTraceV1;
+  /**
+   * Full eligible provider/model membership from a policy evaluation, keyed
+   * "provider\u0000model". The trace's candidate list is bounded; fallback
+   * redirect checks need membership for eligible rows that were truncated out.
+   */
+  policyEligibility?: ReadonlySet<string>;
   /**
    * Set when a blocked-model redirect moved the request to a different
    * provider. Caller credentials addressed to the source route must not follow
@@ -733,6 +739,9 @@ function routeModelInternal(
       ...routed,
       routeKind: "policy" as const,
       routeReason: routed.routeReason === "blocked-model-redirect" ? "blocked-model-redirect" : "policy-selected",
+      policyEligibility: new Set(evaluation.candidates
+        .filter(candidate => candidate.eligible)
+        .map(candidate => candidate.provider + "\u0000" + candidate.model)),
       routeDecision: {
         ...evaluation.trace,
         selected: {

package/src/server/anthropic-rate-limit-headers.ts

@@ -0,0 +1,7 @@
+export function anthropicRateLimitHeaders(upstream: Headers): Record<string, string> {
+  const headers: Record<string, string> = {};
+  upstream.forEach((value, name) => {
+    if (name.startsWith("anthropic-ratelimit-")) headers[name] = value;
+  });
+  return headers;
+}

package/src/server/auth-cors.ts

@@ -32,6 +32,7 @@ import {
 } from "../config/provider-validation";
 import { providerDestinationConfigError } from "../lib/destination-policy";
 import { providerEgressConfigError } from "../lib/provider-egress";
+import { providerTlsProfileConfigError } from "../lib/provider-tls-profile";
 import { redactSecretString } from "../lib/redact";
 import { DECLARABLE_HOSTED_TOOL_TYPES } from "../responses/hosted-tool-policy";
 import { effectiveGoogleMode, getProviderRegistryEntry, providerCodexAccountMode, providerMatchesRegistryTransport, registryEntryForProviderDestination } from "../providers/registry";
@@ -780,6 +781,11 @@ export function providerManagementConfigError(
     return `provider ${name} must not include codexAccountMode`;
   }
   const typed = provider as unknown as OcxProviderConfig;
+  // Every write path (POST, PUT, reload, both PATCH passes) funnels through here, so a PATCH
+  // that changes authMode/baseUrl/adapter under a retained tlsProfile is refused before it
+  // persists a row the config schema would later reject as document-fatal.
+  const tlsProfileError = providerTlsProfileConfigError(name, typed);
+  if (tlsProfileError) return `provider ${JSON.stringify(redactSecretString(name))} ${tlsProfileError}`;
   const baseUrlError = providerBaseUrlConfigError(typed.baseUrl);
   if (baseUrlError) return `provider ${name} ${baseUrlError}`;
   if (effectiveGoogleMode(name, typed) === "vertex" && typed.location !== undefined) {
@@ -1110,6 +1116,7 @@ const PROVIDER_CONFIG_FIELD_POLICY = {
   desktopExecutor: "redacted",
   unsafeAllowNativeLocalExec: "editor",
   nativeLocalExec: "editor",
+  tlsProfile: "editor",
 } as const satisfies Record<keyof OcxProviderConfig, ProviderConfigFieldPolicy>;
 
 type ProviderFieldWithPolicy<Policy extends ProviderConfigFieldPolicy> = {

package/src/server/chat-completions.ts

@@ -53,6 +53,7 @@ import { clientWireLogOf, clientWireOf } from "./inference/client-wire";
 import { directEncodersApply } from "./inference/client-encoder-delivery";
 import { responseWithDeferredRequestLog } from "./relay";
 import { handleResponses } from "./responses";
+import { previewXaiOauthWireModel } from "./responses/core-normalize";
 import { providerConsumesCallerAuthorization } from "../providers/caller-authorization";
 import { captureExplicitOpenAiCallerAuth } from "../providers/openai-sidecar";
 import { captureCallerDirectAuth } from "../providers/caller-authorization";
@@ -177,16 +178,20 @@ async function handleChatCompletionsWithBudget(
   let nativeDecline: ProtocolReasonCode | undefined = "unknown-model";
   try {
     const route = routeModel(config, chatBody.model as string, evidenceFromBody(chatBody));
-    // The native Chat lane sends without re-entering the Responses path, so it
-    // has to apply the key's scope itself. Translated traffic is checked where
-    // every rewrite converges instead.
-    assertRouteAllowedByScope(resolveAdmissionModelScope(config, logIds?.admission), requestedModel, route);
     // Preserve the routed destination for Go recognition, then settle the wire before
     // deriving protocol-scoped affinity. Recognition must not inspect the flipped adapter.
     const routedProvider = route.provider;
     route.staticPolicy = captureRouteStaticPolicy(
       route.providerName, route.modelId, routedProvider, route.staticPolicy.effectiveAlias, "chat",
     );
+    // Native Chat must check its own destination; translated xAI OAuth turns
+    // preview the billed Fast lane before their final Responses scope check.
+    assertRouteAllowedByScope(resolveAdmissionModelScope(config, logIds?.admission), requestedModel, {
+      providerName: route.providerName,
+      modelId: previewXaiOauthWireModel({ options: {
+        serviceTier: typeof chatBody.service_tier === "string" ? chatBody.service_tier : undefined,
+      } }, route, config, "chat"),
+    });
     const wireProvider = resolveWireProtocolOverride(route.providerName, route.modelId, routedProvider, "chat", route.staticPolicy);
     route.provider = resolveOpenCodeGoTransport(
       wireProvider,

package/src/server/claude-messages.ts

@@ -28,6 +28,7 @@ import { recordDesktopRequest } from "../claude/desktop-health";
 import { stripOneMillionMarker } from "../claude/context-windows";
 import { captureClaudeInbound } from "../claude/inbound-debug";
 import { claudeCodeForIngress } from "../claude/intercept/model-bindings";
+import { classifyInterceptClient } from "../claude/intercept/client-class";
 import { analyzeClaudeCompatibility, isClaudeCompatibilityMode } from "../claude/compatibility";
 import { carriesMessageThread, messageThreadUnsupportedResponse } from "../claude/message-threads";
 import {
@@ -39,6 +40,7 @@ import {
   UPSTREAM_RESET_REPLAY_REFUSED_CODE,
 } from "../lib/upstream-retry";
 import { resolveClientRetryAfter } from "../lib/retry-after";
+import { anthropicRateLimitHeaders } from "./anthropic-rate-limit-headers";
 import {
   anthropicErrorBody,
   anthropicErrorResponse,
@@ -72,6 +74,7 @@ import { clientWireOf } from "./inference/client-wire";
 import { directEncodersApply } from "./inference/client-encoder-delivery";
 import type { ClientEncoderOption } from "./responses/core-options";
 import { handleResponses } from "./responses";
+import { previewXaiOauthWireModel } from "./responses/core-normalize";
 import { upstreamWireForAdapter } from "../protocols/contract";
 import { createProtocolEnvelope, type ProtocolEnvelope } from "../protocols/envelope";
 import { featuresFromMessagesBody, type ProtocolFeature } from "../protocols/features";
@@ -82,6 +85,7 @@ import { requestPathForLane } from "../protocols/path";
 import { resolveApiSurfaceSettings, resolveProtocolSettings } from "../protocols/settings";
 import { markProtocolBlocked, markProtocolEntry } from "../protocols/trace";
 import { recordProtocolShadowPlan } from "../protocols/shadow-plan";
+import { captureAnthropicClientIdentity } from "../adapters/anthropic/client-identity";
 import { nativeMessagesDeclineReason, type NativeMessagesSelector } from "./messages-native-eligibility";
 import {
   isApiAuthRequired,
@@ -296,7 +300,7 @@ export interface PassthroughBodyGuard {
 }
 
 type PassthroughCloseReason = "terminal" | "client_cancel" | "body_stall" | "body_overflow";
-type PassthroughFinalizeMeta = { closeReason: PassthroughCloseReason; terminalStatus?: "failed" };
+type PassthroughFinalizeMeta = { closeReason: PassthroughCloseReason; terminalStatus?: "failed" | "incomplete" };
 
 /**
  * Tap an Anthropic-vocabulary SSE stream for the request log (usage + terminal),
@@ -340,6 +344,11 @@ export function tapAnthropicSseForLog(
   };
   const inspect = (chunk: Uint8Array) => {
     buffer += decoder.decode(chunk, { stream: true });
+    // SSE lines may end in CRLF, LF or CR. Normalize the inspection copy to LF (the forwarded
+    // bytes are untouched), holding a trailing CR until the next chunk shows whether an LF
+    // follows it, so a CRLF split across chunks stays one line ending.
+    const heldCr = buffer.endsWith("\r");
+    buffer = (heldCr ? buffer.slice(0, -1) : buffer).replace(/\r\n?/g, "\n") + (heldCr ? "\r" : "");
     let sep: number;
     while ((sep = buffer.indexOf("\n\n")) !== -1) {
       const frame = buffer.slice(0, sep);
@@ -347,6 +356,17 @@ export function tapAnthropicSseForLog(
       inspectFrame(frame);
     }
   };
+  // The last block can sit in the buffer without its blank line: an upstream that stopped after
+  // it, or a held trailing CR. Count it before deciding how the turn ended (the Responses relay
+  // flushes the same candidate). Returns true when this flush found the terminal in a block the
+  // client has not seen a blank line after, so the caller restores one.
+  const flushTail = (): boolean => {
+    const terminalBefore = terminalSeen;
+    const tail = (buffer + decoder.decode()).replace(/\r\n?/g, "\n");
+    buffer = "";
+    if (tail) inspectFrame(tail);
+    return terminalSeen && !terminalBefore && !tail.endsWith("\n\n");
+  };
   const reader = upstream.getReader();
   let settled = false;
   let bodyBytes = 0;
@@ -369,9 +389,25 @@ export function tapAnthropicSseForLog(
     settled = true;
     idle.cancel();
     detachAbort();
+    const terminalInTail = flushTail();
     recordUsage();
-    finalize(200, { closeReason });
-    closeWithErrorFrame(errType, message);
+    if (terminalSeen) {
+      // The turn already ended (message_stop or an upstream error event): an upstream that then
+      // idles or keeps sending did not cut it short. Same rule as the read-error branch,
+      // including the restored blank line for a terminal found only in the tail.
+      finalize(200, { closeReason: "terminal" });
+      try {
+        if (terminalInTail) tapController?.enqueue(encoder.encode("\n\n"));
+        tapController?.close();
+      } catch { /* client already torn down */ }
+    } else {
+      // A cut-short turn, logged as the Responses relay logs a stall-timeout incomplete
+      // (httpStatusForRequestLogTerminal: only a max_output_tokens incomplete is a 200). A 200
+      // row with no terminalStatus also lost its failure diagnostics in usage.jsonl.
+      logCtx.upstreamError = message.slice(0, 500);
+      finalize(502, { terminalStatus: "incomplete", closeReason });
+      closeWithErrorFrame(errType, message);
+    }
     reader.cancel(new DOMException(message, closeReason === "body_stall" ? "TimeoutError" : "QuotaExceededError")).catch(() => {});
   };
   const idle = idleDeadline(guard?.stallMs ?? 0, () => {
@@ -450,12 +486,7 @@ export function tapAnthropicSseForLog(
         settled = true;
         idle.cancel();
         detachAbort();
-        // A read error can follow the last SSE block before its blank-line delimiter. Count
-        // that block before deciding how the turn ended, as the Responses relay does.
-        const terminalBeforeTail = terminalSeen;
-        const tail = buffer + decoder.decode();
-        buffer = "";
-        if (tail) inspectFrame(tail);
+        const terminalInTail = flushTail();
         recordUsage();
         if (isTranslatorBudgetExceededError(err)) {
           // A local cap, not an upstream failure: the non-streaming native Messages fold
@@ -471,7 +502,7 @@ export function tapAnthropicSseForLog(
           try {
             // An SSE parser drops an event that EOF cuts off before its blank line, so restore
             // the delimiter when the terminal was only found in that unterminated tail.
-            if (!terminalBeforeTail) controller.enqueue(encoder.encode("\n\n"));
+            if (terminalInTail) controller.enqueue(encoder.encode("\n\n"));
             controller.close();
           } catch { /* torn down */ }
           reader.cancel(err).catch(() => {});
@@ -598,11 +629,13 @@ async function anthropicNativePassthrough(
   const upstream = result.upstream;
 
   const contentType = upstream.headers.get("content-type") ?? "application/json";
+  const rateLimitHeaders = anthropicRateLimitHeaders(upstream.headers);
   const bodyGuard = resolvePassthroughBodyGuard(config, req.signal);
   if (upstream.ok && contentType.includes("text/event-stream") && upstream.body) {
     return new Response(tapAnthropicSseForLog(upstream.body, logCtx, finalize, bodyGuard), {
       status: upstream.status,
       headers: {
+        ...rateLimitHeaders,
         "Content-Type": contentType,
         "Cache-Control": "no-cache",
         "Connection": "keep-alive",
@@ -647,7 +680,7 @@ async function anthropicNativePassthrough(
   const retryAfter = upstream.headers.get("retry-after");
   return new Response(text, {
     status: upstream.status,
-    headers: { "Content-Type": contentType, ...(retryAfter ? { "Retry-After": retryAfter } : {}) },
+    headers: { ...rateLimitHeaders, "Content-Type": contentType, ...(retryAfter ? { "Retry-After": retryAfter } : {}) },
   });
 }
 
@@ -891,8 +924,10 @@ async function handleClaudeMessagesWithBudget(
       req.headers.get("anthropic-beta") ?? undefined,
     );
     // Client surface discrimination: Desktop 3P aliases resolve through the
-    // desktop registry; Code uses readable aliases or direct model names.
-    if (isRec(anthropicBody) && typeof anthropicBody.model === "string" && resolveDesktop3pAlias(anthropicBody.model)) {
+    // desktop registry; Code uses readable aliases or direct model names. The CLI's first-party
+    // picker also offers registry aliases, so a CLI-classified User-Agent stays the Code surface.
+    if (isRec(anthropicBody) && typeof anthropicBody.model === "string" && resolveDesktop3pAlias(anthropicBody.model)
+      && classifyInterceptClient(req.headers.get("user-agent")) !== "cli") {
       logCtx.surface = "claude-desktop";
       recordDesktopRequest();
     }
@@ -1046,18 +1081,20 @@ async function handleClaudeMessagesWithBudget(
   };
   try {
     const route = routeModel(config, internalBody.model as string, evidenceFromBody(internalBody));
-    // Same reason as the native Chat lane: this route can be sent from here, so
-    // the key's scope is applied before the wire is settled.
-    assertRouteAllowedByScope(
-      resolveAdmissionModelScope(config, logIds?.admission),
-      String(internalBody.model ?? ""),
-      route,
-    );
     // Settle the wire once so the sampling decision below reads the effective
     // adapter rather than the provider-wide default (#404).
     route.staticPolicy = captureRouteStaticPolicy(
       route.providerName, route.modelId, route.provider, route.staticPolicy.effectiveAlias, "anthropic",
     );
+    // Keep native dispatch scoped while translated xAI OAuth requests preview
+    // the same billed Fast lane as their final Responses scope check.
+    assertRouteAllowedByScope(
+      resolveAdmissionModelScope(config, logIds?.admission),
+      String(internalBody.model ?? ""),
+      { providerName: route.providerName, modelId: previewXaiOauthWireModel({ options: {
+        serviceTier: typeof internalBody.service_tier === "string" ? internalBody.service_tier : undefined,
+      } }, route, config, "anthropic") },
+    );
     route.provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, "anthropic", route.staticPolicy);
     logCtx.routeDecision = route.routeDecision;
     settledRoute = route;
@@ -1166,7 +1203,8 @@ async function handleClaudeMessagesWithBudget(
     return await handleNativeMessages({
       req, config, logCtx, ...(logIds ? { logIds } : {}),
       route: nativeMessagesRoute, body: nativeBody, requestedModel, translatorBudget, selector: nativeSelector,
-      // The one caller header the native lane is given; the builder allowlists it.
+      // Compatibility identity is an opaque request-local handle, separate from credentials.
+      clientIdentity: captureAnthropicClientIdentity(req.headers),
       callerAnthropicBeta: req.headers.get("anthropic-beta"),
     });
   }

package/src/server/index/claude-intercept-lifecycle.ts

@@ -8,6 +8,8 @@ import {
   startClaudeIntercept,
   type ClaudeInterceptHandle,
   type StartClaudeInterceptOptions,
+  type ClaudeInterceptOutcome,
+  ClaudeInterceptProxyBindError,
 } from "../../claude/intercept/runtime";
 
 /**
@@ -20,6 +22,8 @@ export interface ClaudeInterceptLifecycle<T> {
   /** True once the TLS listener has bound and `requestServer` is it. */
   ownsListener(requestServer: Server<T>): boolean;
   start(options: StartClaudeInterceptOptions<T>): void;
+  ensure(): Promise<ClaudeInterceptOutcome>;
+  lastOutcome(): ClaudeInterceptOutcome | null;
   stop(): Promise<void>;
 }
 
@@ -53,34 +57,76 @@ export async function loadPickerRoutesFromCatalog(): Promise<PickerRouteInput> {
 
 export function createClaudeInterceptLifecycle<T>(): ClaudeInterceptLifecycle<T> {
   let listener: Server<T> | null = null;
-  let pending: Promise<ClaudeInterceptHandle<T> | null> = Promise.resolve(null);
+  let options: StartClaudeInterceptOptions<T> | undefined;
+  let handle: ClaudeInterceptHandle<T> | null = null;
+  let inflight: Promise<ClaudeInterceptOutcome> | undefined;
+  let stopped = false;
+  let startupPending = false;
+  let retryAfterStartup = false;
+  let observed: ClaudeDesktopModeObservation | undefined;
+  const stateOf = (bound: ClaudeInterceptHandle<T>) => ({ proxyPort: bound.proxyPort, caCertPath: bound.caCertPath, pickerProxyPort: bound.pickerProxyPort, pickerReason: bound.pickerReason ?? null, pickerFailurePort: bound.pickerFailurePort });
+  let outcome: ClaudeInterceptOutcome | null = null;
+  const ensure = (): Promise<ClaudeInterceptOutcome> => {
+    if (stopped) return Promise.resolve(outcome = { ok: false, reason: "stopped" });
+    if (inflight) {
+      if (startupPending) retryAfterStartup = true;
+      return inflight;
+    }
+    if (handle) {
+      if (options) observed = observeClaudeDesktopMode(options.config);
+      return Promise.resolve(outcome = { ok: true, state: stateOf(handle) });
+    }
+    if (!options) return Promise.resolve(outcome = { ok: false, reason: "failed" });
+    const opts = options;
+    const run = async (): Promise<ClaudeInterceptOutcome> => {
+      if (opts.config.runtimeRole === "client") return { ok: false, reason: "client_role" };
+      if (!claudeInterceptEnabled(opts.config)) return { ok: false, reason: "disabled" };
+      if (opts.requestedPort === 0 && typeof opts.config.claudeCode?.intercept?.port !== "number")
+        return { ok: false, reason: "ephemeral_port" };
+      try {
+        observed = observeClaudeDesktopMode(opts.config);
+        handle = await startClaudeIntercept<T>({
+          ...opts,
+          desiredClients: () => buildInterceptDesiredClients(opts.config, observed!)(),
+          loadPickerRoutes: opts.loadPickerRoutes ?? loadPickerRoutesFromCatalog,
+          dispatch: (req, requestServer) => {
+            listener ??= requestServer;
+            return opts.dispatch(req, requestServer);
+          },
+        });
+        if (!handle) return { ok: false, reason: "disabled" };
+        listener = handle.listener;
+        console.log(`🔐 Claude intercept proxy active on http://127.0.0.1:${handle.proxyPort} (CONNECT api.anthropic.com → local TLS)`);
+        return { ok: true, state: stateOf(handle) };
+      } catch (error) {
+        listener = null;
+        console.warn(`⚠ Claude intercept proxy could not start: ${error instanceof Error ? error.message : String(error)}`);
+        return error instanceof ClaudeInterceptProxyBindError && error.code === "EADDRINUSE"
+          ? { ok: false, reason: "port_in_use", port: error.port }
+          : { ok: false, reason: "failed" };
+      }
+    };
+    inflight = run().then(async result => {
+      // An ensure arriving during startup first joins that attempt, then retries its null outcome.
+      if (!result.ok && retryAfterStartup && !stopped) return run();
+      return result;
+    }).then(result => outcome = result).finally(() => {
+      inflight = undefined; startupPending = false; retryAfterStartup = false;
+    });
+    return inflight;
+  };
   return {
     ownsListener: requestServer => listener !== null && requestServer === listener,
-    start(options) {
-      const dispatch = options.dispatch;
-      const observed = observeClaudeDesktopMode(options.config);
-      pending = startClaudeIntercept<T>({
-        ...options,
-        // A disabled Claude surface relays everything while the bound listener lives until restart.
-        desiredClients: buildInterceptDesiredClients(options.config, observed),
-        loadPickerRoutes: options.loadPickerRoutes ?? loadPickerRoutesFromCatalog,
-        dispatch: (req, requestServer) => {
-          listener ??= requestServer;
-          return dispatch(req, requestServer);
-        },
-      }).then(handle => {
-        if (handle) {
-          listener = handle.listener;
-          console.log(`🔐 Claude intercept proxy active on http://127.0.0.1:${handle.proxyPort} (CONNECT api.anthropic.com → local TLS)`);
-        }
-        return handle;
-      }).catch((error: unknown) => {
-        console.warn(`⚠ Claude intercept proxy could not start: ${error instanceof Error ? error.message : String(error)}`);
-        return null;
-      });
-    },
+    start(opts) { options = opts; startupPending = true; void ensure(); },
+    ensure,
+    lastOutcome: () => outcome,
     async stop() {
-      await (await pending)?.stop();
+      stopped = true;
+      await inflight;
+      await handle?.stop();
+      handle = null;
+      listener = null;
+      outcome = { ok: false, reason: "stopped" };
     },
   };
 }

package/src/server/index/optional-listeners.ts

@@ -28,6 +28,8 @@ export interface OptionalListenerStartContext<T> {
 }
 
 export interface OptionalListenerSet<T> {
+  ensureClaudeIntercept(): ReturnType<ClaudeInterceptLifecycle<T>["ensure"]>;
+  claudeInterceptOutcome(): ReturnType<ClaudeInterceptLifecycle<T>["lastOutcome"]>;
   ingressOf(server: Server<T>): ServerIngress | undefined;
   linkRouteAllowed(url: URL, req: Request): boolean;
   linkAdmissionKeyIds(): ReadonlySet<string>;
@@ -68,6 +70,8 @@ export function createOptionalListenerSet<T>(linkDeps: LinkListenerDeps = {}): O
   let supervisorStop: (() => Promise<void>) | undefined;
 
   return {
+    ensureClaudeIntercept: () => claudeIntercept.ensure(),
+    claudeInterceptOutcome: () => claudeIntercept.lastOutcome(),
     ingressOf(server) {
       if (linkListener.ownsListener(server)) return "hub-link";
       if (claudeIntercept.ownsListener(server)) return "claude-intercept";

package/src/server/index/spend-ledger-lifecycle.ts

@@ -7,6 +7,7 @@ import {
   configureSharedSpendLedger,
   spendPolicyFromConfig,
 } from "../../lib/spend-reservation-ledger";
+import { warnIfSyncedStateDirectory } from "../../lib/synced-state-location";
 
 const failedStartRollbacks = new WeakMap<object, Promise<void>>();
 
@@ -34,6 +35,9 @@ export interface SpendLedgerServerLifecycle {
 /** Acquire before config loading so every later startup failure has one rollback owner. */
 export function acquireSpendLedgerServerLifecycle(configDir: string): SpendLedgerServerLifecycle {
   const owner: SpendLedgerOwnerLease = acquireSpendLedgerOwner(configDir);
+  // Advisory: a synced state directory makes the journal's hard-link guard refuse intermittently
+  // (#6314). Said once at startup instead of being discovered from a 502.
+  warnIfSyncedStateDirectory(configDir);
   // Each entry returns whatever the listener's own stop returned. Typed as void-or-promise
   // because the rollback below has to WAIT on it: declaring it `() => void` let the call site
   // compile while statically erasing the promise it needs to await.

package/src/server/management/agent-settings-routes.ts

@@ -1,3 +1,4 @@
+import { ensureManagementClaudeIntercept, interceptStartRefusal, interceptStatus } from "./claude-intercept-routes";
 import { persistCommittedDesktopGateway } from "../../claude/desktop-gateway-state";
 import { captureDesktopAppliedMarker, commitDesktopAppliedMarker } from "../../claude/desktop-applied-marker";
 import { randomUUID } from "node:crypto";
@@ -206,6 +207,20 @@ export function setGrokApplyFlightTestHooks(
 }
 import type { ManagementContext } from "./context";
 
+async function injectionModelOptions(config: OcxConfig, models: readonly CatalogModel[]) {
+  const disabled = new Set(config.disabledModels ?? []);
+  const { listCatalogNativeSlugs } = await import("../../codex/catalog");
+  const nativeModels = listCatalogNativeSlugs()
+    .filter(slug => !disabled.has(slug))
+    .map(slug => ({ provider: "openai", model: slug, namespaced: slug }));
+  const routedModels = uniqueCatalogModelsForPublicList([...models])
+    .map(m => ({ provider: m.provider, model: m.id, namespaced: catalogModelSlug(m) }))
+    .filter(m => ![...disabled].some(stored => (
+      stored === m.namespaced || slugEquals(stored, m.provider, m.model)
+    )));
+  return [...nativeModels, ...routedModels];
+}
+
 export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise<Response | null> {
   const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
 
@@ -547,18 +562,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   // effort the prompt tells the agent to pass to spawn_agent. GET returns the current
   // picks + available models/efforts; PUT sets or clears them.
   if (url.pathname === "/api/injection-model" && req.method === "GET") {
-    const models = await fetchAllModels(config);
-    const disabled = new Set(config.disabledModels ?? []);
-    const { listCatalogNativeSlugs } = await import("../../codex/catalog");
     const { CODEX_REASONING_LEVELS } = await import("../../reasoning-effort");
-    const nativeModels = listCatalogNativeSlugs()
-      .filter(slug => !disabled.has(slug))
-      .map(slug => ({ provider: "openai", model: slug, namespaced: slug }));
-    const routedModels = uniqueCatalogModelsForPublicList(models)
-      .map(m => ({ provider: m.provider, model: m.id, namespaced: catalogModelSlug(m) }))
-      .filter(m => ![...disabled].some(stored => (
-        stored === m.namespaced || slugEquals(stored, m.provider, m.model)
-      )));
     return jsonResponse({
       multiAgentGuidanceEnabled: multiAgentGuidanceEnabled(config),
       syncCodexSubagentDefaults: subagentDefaultSyncEffective(config),
@@ -566,9 +570,41 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       effort: config.injectionEffort ?? null,
       prompt: config.injectionPrompt ?? null,
       efforts: CODEX_REASONING_LEVELS.map(l => l.effort),
-      available: [...nativeModels, ...routedModels],
+      available: await injectionModelOptions(config, await fetchAllModels(config)),
     });
   }
+  // Read-only: sizes the described delegated work and proposes a model and effort from the
+  // same options GET offers. The page applies an accepted proposal through the PUT below.
+  if (url.pathname === "/api/injection-model/suggest" && req.method === "POST") {
+    let body: unknown;
+    try { body = await readManagementJsonBody(req); } catch (error) {
+      rethrowManagementBodyTooLarge(error);
+      return jsonResponse({ error: "invalid JSON body" }, 400);
+    }
+    const { work, model } = (body ?? {}) as { work?: unknown; model?: unknown };
+    const { ROLE_INSTRUCTIONS_EXCERPT_CHARS } = await import("../../codex/role-sizing");
+    if (typeof work !== "string" || work.trim() === "" || work.length > ROLE_INSTRUCTIONS_EXCERPT_CHARS) {
+      return jsonResponse({ error: `work must be a nonblank string of at most ${ROLE_INSTRUCTIONS_EXCERPT_CHARS} characters`, code: "invalid_work" }, 400);
+    }
+    if (model !== undefined && typeof model !== "string") {
+      return jsonResponse({ error: "model must be a string", code: "invalid_model" }, 400);
+    }
+    const { proposeDelegationModel, NoSizingModelError } = await import("./codex-role-auto-assign");
+    const models = await (deps.fetchAllModels ?? fetchAllModels)(config);
+    try {
+      return jsonResponse(await proposeDelegationModel({
+        config,
+        work: work.trim(),
+        offered: (await injectionModelOptions(config, models)).map(option => option.namespaced),
+        ...(typeof model === "string" ? { sizingModel: model } : {}),
+        models,
+        ...(deps.completeCodexRoleSizing ? { completeRoleSizing: deps.completeCodexRoleSizing } : {}),
+      }));
+    } catch (error) {
+      if (error instanceof NoSizingModelError) return jsonResponse({ error: error.message, code: "no_sizing_model" }, 409);
+      throw error;
+    }
+  }
   if (url.pathname === "/api/injection-model" && req.method === "PUT") {
     let parsedBody: unknown;
     try { parsedBody = await readManagementJsonBody(req); } catch (error) {
@@ -729,20 +765,13 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   // the first five eligible visible rows by display priority; OCX guidance uses natural ranks.
   if (url.pathname === "/api/subagent-models" && req.method === "GET") {
     const models = await (deps.fetchAllModels ?? fetchAllModels)(config);
-    const disabled = new Set(config.disabledModels ?? []);
     // Native gpt (passthrough) are also valid subagent picks — they're picker-visible models in the
     // catalog, just buried by priority. List them first so the user can feature them over routed.
-    const { listCatalogNativeSlugs } = await import("../../codex/catalog");
-    const visibleRouted = [...new Set(models
-      .filter(m => ![...disabled].some(stored =>
-        stored === catalogModelSlug(m) || slugEquals(stored, m.provider, m.id)
-      ))
-      .map(catalogModelSlug))];
+    const [{ listCatalogNativeSlugs }, { subagentSelectableModels }] = await Promise.all([
+      import("../../codex/catalog"),
+      import("../../codex/subagent-selectable-models"),
+    ]);
     const chosen = config.subagentModels ?? [];
-    const selectable = [
-      ...listCatalogNativeSlugs().filter(ns => !disabled.has(ns)),
-      ...visibleRouted,
-    ];
     // A saved roster slot must stay representable even after its model is disabled
     // elsewhere (Models page, provider allowlist, a provider row going away). The
     // dashboard treats `available` as the set of rows it can render, so a chosen id
@@ -751,11 +780,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     // deliberate 5-model roster to an unrelated visibility toggle is data loss, not a
     // filter. Same reasoning as `fetchGrokCandidateModels`, which deliberately lists a
     // model the user already excluded so its switch remains reachable.
-    const selectableSet = new Set(selectable);
-    const available = [
-      ...selectable,
-      ...[...new Set(chosen)].filter(model => !selectableSet.has(model)),
-    ];
+    const available = subagentSelectableModels(config, models, listCatalogNativeSlugs());
     // #857: let CLI/GUI show when a running Codex app-server keeps an older
     // in-memory catalog than the one on disk. Bounded request-path read: the synchronous
     // collector blocked the event loop for the whole Windows CIM walk (4-7s measured).
@@ -1114,6 +1139,13 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         }
       }
       if (desktopMode === "first-party") {
+        const refusal = interceptStartRefusal(ctx);
+        if (refusal) return refusal;
+        const started = await ensureManagementClaudeIntercept(ctx);
+        if (!started.ok) return jsonResponse({ ...started, code: started.reason }, 409);
+        const { claudeInterceptProxyPort } = await import("../../claude/intercept/runtime");
+        const configured = claudeInterceptProxyPort(config, config.port ?? 10100);
+        if (started.state.proxyPort !== configured) return jsonResponse({ ok: false, code: "port_mismatch", bound: started.state.proxyPort, configured }, 409);
         const { setIntegrationEnabled } = await import("../../codex/desired-state");
         const desired = setIntegrationEnabled("claude-desktop", true);
         if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
@@ -1299,6 +1331,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         stale: firstPartySeen.stale,
         interceptEnabled: firstPartySeen.interceptEnabled,
         interceptRunning: intercept !== null,
+        ...interceptStatus(ctx),
         proxyPort: intercept?.proxyPort ?? firstPartySeen.proxyPort,
         caCertPath: firstPartySeen.caCertPath,
         // What the running proxy routes with right now (live config), not the file on disk.
@@ -1471,6 +1504,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       cliFirstParty: config.claudeCode?.cliFirstParty === true,
       cliFirstPartyApplied: config.claudeCode?.cliFirstParty === true && sharedProxy === "live",
       desktopFirstParty: desired.desktop,
+      ...interceptStatus(ctx),
       interceptEligible: eligible,
       interceptRunning: bound !== null && eligible,
       sharedProxy,
@@ -1540,14 +1574,17 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       const { captureDesktopFirstPartyRollback, inspectDesktopFirstParty, observeClaudeDesktopMode, resolveClaudeDesktopMode } = await import("../../claude/desktop-first-party");
       const { firstPartyDesired, readFirstPartyProxyStatus, reconcileClaudeFirstPartySettings } = await import("../../claude/first-party-settings");
       const { commitClaudeCodeBlock } = await import("../../claude/claude-code-block");
-      const bound = (deps.getClaudeInterceptState ?? getClaudeInterceptState)();
+      let bound = (deps.getClaudeInterceptState ?? getClaudeInterceptState)();
       if (body.cliFirstParty) {
-        if (!claudeInterceptEnabled(config)) return jsonResponse({ error: "Claude intercept is disabled", code: "intercept_disabled" }, 409);
-        if (bound === null) return jsonResponse({ error: "Claude intercept is unavailable", code: "intercept_unavailable" }, 409);
+        const startRefusal = interceptStartRefusal(ctx);
+        if (startRefusal) return startRefusal;
+        const started = await ensureManagementClaudeIntercept(ctx);
+        if (!started.ok) return jsonResponse({ ...started, code: started.reason }, 409);
+        bound = started.state;
         const targetPort = claudeInterceptProxyPort(config, config.port ?? 10100);
         if (targetPort !== bound.proxyPort) return jsonResponse({
-          error: `Claude intercept port mismatch (configured ${targetPort}, bound ${bound.proxyPort}); restart needed`,
-          code: "intercept_unavailable",
+          error: `Claude intercept port mismatch (configured ${targetPort}, bound ${bound.proxyPort})`,
+          code: "port_mismatch", bound: bound.proxyPort, configured: targetPort,
         }, 409);
         let inspection: ReturnType<typeof inspectDesktopFirstParty>["settings"];
         try { inspection = inspectDesktopFirstParty(config).settings; }
@@ -1559,7 +1596,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       try { if (body.cliFirstParty) restoreSettings = captureDesktopFirstPartyRollback(config); }
       catch { return jsonResponse({ error: "Claude settings are unreadable", code: "unreadable" }, 500); }
       type FirstPartyMutation =
-        | { refusal: { error: string; code: "intercept_disabled" | "intercept_unavailable" } }
+        | { refusal: { error: string; code: "disabled" | "port_mismatch"; bound?: number; configured?: number } }
         | { claudeCode: OcxConfig["claudeCode"]; previous: { present: boolean; value: boolean };
             pinnedMode: "first-party" | "gateway" | undefined; retainedAmbiguous: boolean };
       let outcome: ReturnType<typeof mutatePersistedConfig<FirstPartyMutation>>;
@@ -1567,11 +1604,11 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         outcome = mutatePersistedConfig<FirstPartyMutation>(persisted => {
         if (body.cliFirstParty) {
           if (!claudeInterceptEnabled(persisted)) return { changed: false, value: {
-            refusal: { error: "Claude intercept is disabled", code: "intercept_disabled" as const } } };
+            refusal: { error: "Claude intercept is disabled", code: "disabled" as const } } };
           const persistedPort = claudeInterceptProxyPort(persisted, persisted.port ?? 10100);
           if (bound === null || persistedPort !== bound.proxyPort) return { changed: false, value: {
-            refusal: { error: `Claude intercept port mismatch (configured ${persistedPort}, bound ${bound?.proxyPort ?? "none"}); restart needed`,
-              code: "intercept_unavailable" as const } } };
+            refusal: { error: `Claude intercept port mismatch (configured ${persistedPort}, bound ${bound?.proxyPort ?? "none"})`,
+              code: "port_mismatch" as const, bound: bound?.proxyPort, configured: persistedPort } } };
         }
         const before = structuredClone(persisted);
         const previous = { present: Object.hasOwn(persisted.claudeCode ?? {}, "cliFirstParty"),