@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/server/effort-policy.ts

@@ -15,7 +15,7 @@
 import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../types";
 import { modelInList } from "../types";
 import { codexEffortRank, configuredReasoningEfforts, isCodexReasoningEffort, isDeclaredReasoningEffort, modelRecordValue } from "../reasoning-effort";
-import { catalogModelEfforts } from "../codex/catalog";
+import { catalogModelEfforts } from "../codex/catalog/effort";
 
 /**
  * True when the request carries codex-rs's spawned-child markers, matched EXACTLY.

package/src/server/images.ts

@@ -27,9 +27,11 @@ import { formatCodexProviderForLog } from "../codex/routing";
 import { signalWithTimeout } from "../lib/abort";
 import { readBoundedResponseBytes, type BoundedBytesResult } from "../lib/bounded-body";
 import { sidecarEnter } from "../lib/sidecar-tracker";
+import { isNonReplayableResponse } from "../lib/upstream-retry";
 import type { OcxConfig } from "../types";
 import { resolveFirstUsableOpenAiSidecar, selectImagesProvider } from "../providers/openai-sidecar";
-import { selectProactiveApiKeyTransport } from "../providers/key-failover";
+import { recordDistributedKeyFailure, selectProactiveApiKeyTransport } from "../providers/key-failover";
+import { requestPacingOverloadResponse } from "./responses/pacing-overload";
 import { getProviderRegistryEntry } from "../providers/registry";
 import { readJsonRequestBody, resolveInboundBodyLimitBytes } from "./request-decompress";
 import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "./auth-cors";
@@ -756,6 +758,7 @@ export async function handleImages(
     catch { console.error("[images] Failed to release probe lease"); }
   };
   let url: string;
+  let recordKeyFailure = (_status: 401 | 429, _retryAfter: string | null) => {};
   // Each branch is re-checked as it is entered: the forward check is defence in
   // depth for the pre-filter above, and the keyed check runs before a key
   // rotation is committed.
@@ -805,8 +808,15 @@ export async function handleImages(
     //
     // Transport variant: this branch reads `provider.baseUrl` and `provider.headers` to build
     // the URL and the request, and it comes back with the credential already resolved.
-    const warmKeyProvider = selectProactiveApiKeyTransport(config, providerName, candidates.keyed.provider);
+    let warmKeyProvider;
+    try { warmKeyProvider = selectProactiveApiKeyTransport(config, providerName, candidates.keyed.provider); }
+    catch (error) {
+      const refusal = requestPacingOverloadResponse(error);
+      if (refusal) return refusal;
+      throw error;
+    }
     const provider = warmKeyProvider ?? candidates.keyed.provider;
+    recordKeyFailure = (status, retryAfter) => { recordDistributedKeyFailure(config, providerName, provider._apiKeyAttempt, status, Date.now(), retryAfter); };
     // No fall back to the earlier snapshot once a pick has happened. The picker COMMITS its
     // choice before returning, so if the chosen reference will not resolve -- revoked keychain
     // entry, unset env var -- sending the previous key would authenticate a non-idempotent
@@ -865,6 +875,9 @@ export async function handleImages(
       // compact already set this; the credential-bearing sidecars did not.
       redirect: "manual",
     });
+    if ((upstreamResponse.status === 401 || upstreamResponse.status === 429) && !isNonReplayableResponse(upstreamResponse)) {
+      recordKeyFailure(upstreamResponse.status, upstreamResponse.headers.get("retry-after"));
+    }
     const observed = await readImageResponseBytes(upstreamResponse, {
       maxBytes: IMAGES_RESPONSE_MAX_BYTES,
       signal: linkedSignal.signal,

package/src/server/index/desktop-compatibility-startup.ts

@@ -0,0 +1,56 @@
+import type { OcxConfig } from "../../types";
+import { siblingOfLivePort } from "../../codex/sibling-start";
+import { isTestHomeGuardArmed } from "../../lib/test-home-guard";
+import type { DesktopCompatibilityRuntime } from "../../codex/desktop-compatibility/runtime";
+import { bindNativeCompatibilityOwner } from "../../codex/desktop-compatibility/routing-binding";
+import type { ReadinessGate } from "../readiness";
+
+type RuntimeModule = { getDesktopCompatibilityRuntime(): DesktopCompatibilityRuntime; shutdownDesktopCompatibility(): Promise<void> };
+interface StartupIo {
+  platform?: string;
+  testGuard?: boolean;
+  sibling?: boolean;
+  load?: () => Promise<RuntimeModule>;
+  warn?: (message: string) => void;
+  boundPort?: number;
+  boundHostname?: string;
+  loopbackPort?: number;
+  readiness?: Pick<ReadinessGate, "getStatus">;
+  readinessTimeoutMs?: number;
+}
+/** Core-safe gate: off installs do not load the optional runtime, read credentials or start timers. */
+export function scheduleDesktopCompatibilityStartup(config: OcxConfig, io: StartupIo = {}): { shutdown(): Promise<void> } {
+  let stopped = false, module: RuntimeModule | undefined;
+  let cancelReadiness: (() => void) | undefined;
+  const waitForReadiness = () => !io.readiness ? Promise.resolve(true) : new Promise<boolean>(resolve => {
+    const deadline = Date.now() + (io.readinessTimeoutMs ?? 120000);
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (ready: boolean) => { if (timer) clearTimeout(timer); cancelReadiness = undefined; resolve(ready); };
+    cancelReadiness = () => finish(false);
+    const check = () => {
+      const status = io.readiness!.getStatus();
+      if (stopped || status !== "pending" || Date.now() >= deadline) { finish(!stopped && status === "ready"); return; }
+      timer = setTimeout(check, 100); timer.unref();
+    };
+    check();
+  });
+  const unbind = io.boundPort === undefined || io.boundHostname === undefined ? () => {} : bindNativeCompatibilityOwner({ config, hostname: io.boundHostname, port: io.boundPort, loopbackPort: io.loopbackPort });
+  const enabled = config.desktopCompatibility?.startOnProxyStart === true && (io.platform ?? process.platform) === "win32"
+    && !(io.testGuard ?? isTestHomeGuardArmed()) && !(io.sibling ?? siblingOfLivePort() !== null)
+    && config.runtimeRole !== "client";
+  const pending = enabled ? Promise.resolve().then(async () => {
+    if (stopped) return;
+    if (io.readiness) {
+      const ready = await waitForReadiness();
+      if (stopped) return;
+      if (!ready) throw new Error("desktop_compatibility_startup_not_ready");
+    }
+    module = await (io.load?.() ?? import("../../codex/desktop-compatibility/service"));
+    if (stopped) return;
+    await module.getDesktopCompatibilityRuntime().start();
+  }).catch(() => { (io.warn ?? console.warn)("Desktop compatibility observation did not start. Inspect Desktop compatibility status; no automatic trust or correction was applied."); }) : Promise.resolve();
+  return { async shutdown() {
+    stopped = true; cancelReadiness?.(); unbind(); await pending;
+    if (module) await module.shutdownDesktopCompatibility();
+  } };
+}

package/src/server/index/model-alias-id.ts

@@ -0,0 +1,36 @@
+import { fastRowBases } from "../fast-row";
+import { previewRouteModel } from "../../router";
+import type { OcxConfig } from "../../types";
+
+/**
+ * Build the alias promoter for one model listing. The Fast-base inventory walks
+ * the configured catalog, so it is computed at most once per listing instead of
+ * once per aliased row.
+ */
+export function modelAliasIdPromoter(config: OcxConfig) {
+  let isFastBase: ((id: string) => boolean) | undefined;
+  const fastBases = () => (isFastBase ??= fastRowBases(config));
+  return (provider: string, model: string, alias: string, fastEligible: boolean) =>
+    preferredModelAliasId(config, provider, model, alias, fastEligible, fastBases);
+}
+
+/** Promote only a short alias whose ordinary route is this exact upstream model. */
+export function preferredModelAliasId(
+  config: OcxConfig, provider: string, model: string, alias: string, fastEligible: boolean,
+  fastBases: () => (id: string) => boolean = () => fastRowBases(config),
+): string | undefined {
+  if (config.preferModelAliasIds !== true) return undefined;
+  // Built-in bare aliases are not stable Fast bases. Preserve the qualified ID
+  // when promotion would publish a synthetic sibling that ingress cannot parse.
+  if (config.fastRows !== false && fastEligible && !fastBases()(alias)) return undefined;
+  try {
+    // Preview cannot consume a combo's round-robin selection state. A policy/combo,
+    // reserved native name or another provider's native id must keep its own meaning.
+    const route = previewRouteModel(config, alias);
+    return route.routeReason === "model-alias" && route.providerName === provider && route.modelId === model
+      ? alias : undefined;
+  } catch {
+    // An ambiguous alias stays available through the existing qualified public id.
+    return undefined;
+  }
+}

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

@@ -21,6 +21,7 @@ export { LINK_INGRESS_HOSTNAME } from "./link-listener";
 import type { ServerIngress } from "./serve-options";
 
 export interface OptionalListenerStartContext<T> {
+  startProxy?: typeof import("../../claude/intercept/connect-proxy").startConnectProxy;
   config: OcxConfig;
   publicPort: number;
   requestedPort?: number;
@@ -106,6 +107,7 @@ export function createOptionalListenerSet<T>(linkDeps: LinkListenerDeps = {}): O
       }
       supervisorStop = () => supervisor.stop();
       claudeIntercept.start({
+        startProxy: ctx.startProxy,
         config: ctx.config,
         publicPort: ctx.publicPort,
         requestedPort: ctx.requestedPort,

package/src/server/index/serve-options.ts

@@ -1,4 +1,5 @@
 import type { Server, ServerWebSocket } from "bun";
+import { modelAliasIdPromoter } from "./model-alias-id";
 import type { StartServerDeps } from "./startup-warnings";
 import { isLinkManagementPath } from "../../link/management-routes";
 import {
@@ -1055,7 +1056,7 @@ export function createServeOptions(ctx: ServeOptionsContext) {
           );
           const { buildAnthropicModelInfos } = await import("../../claude/model-info");
           const { resolveAutoContext } = await import("../../claude/context-windows");
-          const { activeDesktop3pAlias } = await import("../../claude/desktop-3p");
+          const { resolvableDesktop3pAlias } = await import("../../claude/desktop-3p");
           // Per-surface id family (devlog 050): explicit ?ids= wins; otherwise the
           // Claude Code CLI discovery UA (`claude-code/<version>`, binary n_()) gets
           // readable claude-ocx ids and every other client (Desktop 3P) keeps the
@@ -1071,7 +1072,7 @@ export function createServeOptions(ctx: ServeOptionsContext) {
             goOrdered,
             resolveAutoContext(config.claudeCode),
             idStyle,
-            activeDesktop3pAlias,
+            resolvableDesktop3pAlias,
             desktopInputs.nativeContextCap,
             config.fastMode,
             // Explicit opt-out omits the Fast predicate.
@@ -1252,6 +1253,7 @@ export function createServeOptions(ctx: ServeOptionsContext) {
             effortRowKnownIds,
           ));
         };
+        const promoteAliasId = modelAliasIdPromoter(config);
         const routedRows = await Promise.all(uniqueCatalogModelsForRawPublicList(goOrdered)
           .filter(m => listAllows(m.provider, m.id))
           .map(async m => {
@@ -1269,8 +1271,11 @@ export function createServeOptions(ctx: ServeOptionsContext) {
                 knownModelIdsForProvider(m.provider, provider, config),
               ).get(m.id)
             : undefined;
+          const effectiveId = !isCombo && !fastModelId && effective
+            ? promoteAliasId(m.provider, m.id, effective.alias, catalogRowFastEligible(m)) ?? publicId
+            : publicId;
           const row = {
-            id: publicId,
+            id: effectiveId,
             object: "model",
             created: 0,
             // This endpoint is an OpenAI-compatible inbound contract. Some clients use
@@ -1279,6 +1284,9 @@ export function createServeOptions(ctx: ServeOptionsContext) {
             owned_by: isCombo ? "openai" : (m.owned_by ?? m.provider),
             ...(isCombo ? { is_combo: true } : {}),
             ...(effective ? { alias_of: `${provider?.alias || m.provider}/${effective.alias}` } : {}),
+            // When preferModelAliasIds promotes the alias to `id`, retain the original
+            // provider/nativeId so clients that need the upstream identity can read it.
+            ...(effectiveId !== publicId ? { native_id: publicId } : {}),
             ...grokEffortFields(m.reasoningEfforts ?? [], m.defaultReasoningEffort),
             ...modelCapabilityFields({
               reasoningEfforts: m.reasoningEfforts,

package/src/server/index/startup-warnings.ts

@@ -149,6 +149,8 @@ export function withRequestLogId(response: Response, requestId: string): Respons
 }
 
 export interface StartServerDeps {
+  /** Test-only CONNECT binder; permits kernel-assigned ports without probe-and-release races. */
+  startClaudeInterceptProxy?: typeof import("../../claude/intercept/connect-proxy").startConnectProxy;
   /** Test-only seam; production always initializes its own management credential state. */
   managementAuthState?: ManagementAuthState;
   /** Test-only route dependencies, forwarded only after management admission succeeds. */
@@ -277,3 +279,12 @@ export function warnPlaintextV2AgentMessagesStartup(config: { plaintextV2AgentMe
   console.warn("   Eligible ChatGPT collaboration calls may carry plaintext message arguments. HTTPS remains encrypted, but task text may be retained in Codex history, selected providers, and local response/debug state.");
   console.warn("   This depends on undocumented ChatGPT and Codex behavior; it does not decrypt existing tasks.");
 }
+
+export function logProxyEndpoints(actualPort: number): void {
+  console.log(`🚀 opencodex proxy running on http://localhost:${actualPort}`);
+  console.log(`   POST /v1/responses → provider translation`);
+  console.log(`   POST /v1/chat/completions → OpenAI-compatible clients`);
+  console.log(`   GET  /healthz      → health check`);
+  console.log(`   GET  /api/*        → management API`);
+  console.log(`   GET  /             → GUI dashboard`);
+}

package/src/server/index/websocket-handler.ts

@@ -30,7 +30,9 @@ import {
 } from "../ws-bridge";
 import {
   CodexAccountCooldownError,
+  CodexMainAccountHardLockError,
   cooldownErrorMessage,
+  cooldownErrorResponse,
 } from "../../codex/auth-context";
 import { codexAccountNamespaceForModel } from "../../codex/account-namespace-match";
 import {
@@ -368,6 +370,13 @@ export function createWebsocketHandler(
                 const accountSelector = typeof payload.model === "string"
                   ? codexAccountNamespaceForModel(config.codexAccountNamespaces, payload.model)
                   : undefined;
+                if (err instanceof CodexMainAccountHardLockError) {
+                  // Same terminal usage-limit body and Retry-After as HTTP (#7046).
+                  const refusal = cooldownErrorResponse(err, Date.now(), accountSelector);
+                  const body = await refusal.json() as { error: Record<string, unknown> };
+                  sendJsonFrame(ws, buildWsErrorFrame(429, body.error, refusal.headers));
+                  return;
+                }
                 sendJsonFrame(ws, buildWsErrorFrame(429, {
                   type: "rate_limit_error",
                   message: cooldownErrorMessage(err, accountSelector),

package/src/server/index.ts

@@ -1,4 +1,5 @@
 import { remoteWorkspaceEnabled } from "../remote-control/workspace-activation";
+import { scheduleDesktopCompatibilityStartup } from "./index/desktop-compatibility-startup";
 import { AuxiliaryListenerBindError } from "./ports";
 import { runAdmittedBodyWork } from "./inbound-body-admission";
 import {
@@ -24,6 +25,7 @@ import {
   websocketsEnabled,
 } from "../config";
 import { flushConfigDirHardeningAndReaps } from "../config/paths";
+import { trackBackgroundWork } from "../lib/background-work";
 import { migrateStartupSubagentModels } from "./subagent-models-startup";
 import { migrateStartupXaiResponses } from "./xai-responses-startup";
 import { migrateStartupZaiResponses } from "./zai-responses-startup";
@@ -62,6 +64,7 @@ import {
 } from "../lib/app-owned-memory-stores";
 import { acquireServerBackgroundLifecycle } from "./background-lifecycle";
 import { startPackageRefresh, stopPackageRefresh } from "../update/refresh-scheduler";
+import { activateAdvisor } from "../lib/advisor-activation";
 import { activateLab, labActivationRequired } from "../lib/lab-activation";
 import { runOpenAiTierStartupMigration } from "../providers/openai-tier-startup";
 import { runAlibabaRegionStartupMigration } from "../providers/alibaba-region-startup";
@@ -198,7 +201,7 @@ import { createReadinessGate, type ReadinessGate } from "./readiness";
 import { createServeOptions, type ServerIngress } from "./index/serve-options";
 import { createOptionalListenerSet, LINK_INGRESS_HOSTNAME } from "./index/optional-listeners";
 import { createPackageTreeIntegrityGuardForServer } from "./index/package-tree-guard";
-import { inspectStartupOwnership, resolveInboundBodyLimitWithWarning, setStartupCacheInvalidationWrite, warnAgentTaskRecoveryStartup, warnPlaintextV2AgentMessagesStartup, type StartServerDeps } from "./index/startup-warnings";
+import { inspectStartupOwnership, logProxyEndpoints, resolveInboundBodyLimitWithWarning, setStartupCacheInvalidationWrite, warnAgentTaskRecoveryStartup, warnPlaintextV2AgentMessagesStartup, type StartServerDeps } from "./index/startup-warnings";
 import { acquireSpendLedgerServerLifecycle, recordFailedStartRollback, type SpendLedgerServerLifecycle } from "./index/spend-ledger-lifecycle";
 export { waitForFailedStartRollback } from "./index/spend-ledger-lifecycle";
 
@@ -638,11 +641,14 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
   let unregisterQuotaAutoRefresh: (() => void) | null = null;
   let remoteWorkspaceStopping = false;
   let remoteWorkspaceShutdown: (() => Promise<void>) | undefined;
+  let desktopCompatibilityStartup: ReturnType<typeof scheduleDesktopCompatibilityStartup> | undefined;
+  let desktopCompatibilityShutdown: (() => Promise<void>) | undefined;
   const managementApiDeps: ManagementApiDeps = {
     ...deps.managementApi,
     listLowQuotaEvents: limit => backgroundLifecycle?.listLowQuotaEvents(limit) ?? [],
     remoteWorkspaceStopping: () => remoteWorkspaceStopping,
     onRemoteWorkspaceShutdown: shutdown => { remoteWorkspaceShutdown = shutdown; }, linkSupervisor: () => optionalListeners.linkSupervisor(), linkListener: () => optionalListeners,
+    onDesktopCompatibilityShutdown: shutdown => { desktopCompatibilityShutdown = shutdown; },
   };
   let workspaceRuntimeFlight: Promise<typeof import("../remote-control/workspace-runtime")> | undefined;
   const loadRemoteWorkspaceRuntime = () => {
@@ -732,7 +738,7 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
         throw new AuxiliaryListenerBindError("hub.managementIngress", managementIngressPort, "127.0.0.1", error);
       }
     }
-    optionalListeners.start({ config, publicPort: server.port ?? listenPort, requestedPort: listenPort,
+    optionalListeners.start({ config, publicPort: server.port ?? listenPort, requestedPort: listenPort, startProxy: deps.startClaudeInterceptProxy,
       maxRequestBodySize: inboundBodyLimitBytes, dispatch: (req, requestServer) => serveOptions.fetch(req, requestServer) });
   } catch (error) {
     unregisterQuotaAutoRefresh?.();
@@ -772,6 +778,7 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
             : []),
           () => optionalListeners.stop(),
           async () => { await remoteWorkspaceShutdown?.(); },
+          async () => { await desktopCompatibilityStartup?.shutdown(); await desktopCompatibilityShutdown?.(); },
           async () => {
             try {
               userCostOverlayReconciler?.stop();
@@ -801,13 +808,7 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
   boundPort = actualPort;
   setCorsOrigin(actualPort);
 
-  console.log(`🚀 opencodex proxy running on http://localhost:${actualPort}`);
-  console.log(`   POST /v1/responses → provider translation`);
-  console.log(`   POST /v1/chat/completions → OpenAI-compatible clients`);
-  console.log(`   GET  /healthz      → health check`);
-  console.log(`   GET  /api/*        → management API`);
-  console.log(`   GET  /             → GUI dashboard`);
-
+  logProxyEndpoints(actualPort);
   if (loopbackServer) {
     // Loud on every start, not once at enable time. An operator who inherits a config, or
     // who forgot, has to be able to see that an unauthenticated surface is live without
@@ -843,7 +844,7 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
     && isCanonicalOpenAiForwardProvider(openAiProvider)
     && providerCodexAccountMode("openai", openAiProvider) === "pool"
   ) {
-    import("../codex/plan-from-token")
+    void trackBackgroundWork("codex-pool-quota-prime-startup", import("../codex/plan-from-token")
       .then(({ reconcileCodexPlansFromTokens }) => {
         try {
           reconcileCodexPlansFromTokens(config);
@@ -853,7 +854,7 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
         return import("../codex/auth-api");
       })
       .then(({ primeCodexPoolQuotas }) => primeCodexPoolQuotas(config, "startup"))
-      .catch(() => {});
+      .catch(() => {}));
   }
 
   // Opt-in storage policy (default OFF). Never blocks listen; cancellable on shutdown.
@@ -864,6 +865,7 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
   // startServer returns, in the same turn as Bun.serve, so a policy route can never be
   // evaluated before its evidence provider is registered. That ordering is load-bearing:
   // the subagent-fallback chain routes synchronously and has nowhere to await.
+  activateAdvisor(config);
   const labConfigDir = getConfigDir();
   if (labActivationRequired(config, labConfigDir)) {
     activateLab(config, labConfigDir);
@@ -879,6 +881,7 @@ function startServerWithSpendLedgerOwner(port: number | undefined, deps: StartSe
   }
 
   startPackageRefresh();
+  desktopCompatibilityStartup = scheduleDesktopCompatibilityStartup(config, { boundHostname: bindHost, boundPort: actualPort, loopbackPort: loopbackServer?.port ?? undefined, readiness: deps.readinessGate });
   return server;
 }
 

package/src/server/inference/advisor-diagnostics.ts

@@ -0,0 +1,31 @@
+import type { RequestLogContext } from "../request-log";
+import { ADVISOR_INTERNAL_CAPABILITY_HEADER, isInternalCallCapability } from "../../lib/local-internal-call-capability";
+
+export const ADVISOR_REASONING_HEADER = "x-opencodex-advisor-reasoning";
+const EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
+
+/** Native Chat sends the finalized body directly instead of the translating adapter builder. */
+export function observeAdvisorNativeReasoning(headers: Headers, log: RequestLogContext, body: string): void {
+  if (!isInternalCallCapability(headers.get(ADVISOR_INTERNAL_CAPABILITY_HEADER))) return;
+  delete log.effectiveEffort;
+  try {
+    const effort = JSON.parse(body)?.reasoning_effort;
+    if (typeof effort === "string" && EFFORTS.has(effort)) log.effectiveEffort = effort;
+  } catch { /* absence of evidence stays unreported */ }
+}
+
+/** Only the authenticated internal caller receives adapter-owned serialization evidence. */
+export function attachAdvisorReasoning(response: Response, log: RequestLogContext): Response {
+  const headers = new Headers(response.headers);
+  headers.set(ADVISOR_REASONING_HEADER, JSON.stringify({
+    effectiveEffort: log.effectiveEffort && EFFORTS.has(log.effectiveEffort) ? log.effectiveEffort : null,
+  }));
+  return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}
+
+export function readAdvisorReasoning(headers: Headers): string | null {
+  try {
+    const value = JSON.parse(headers.get(ADVISOR_REASONING_HEADER) ?? "null")?.effectiveEffort;
+    return typeof value === "string" && EFFORTS.has(value) ? value : null;
+  } catch { return null; }
+}

package/src/server/inference/client-encoder-delivery.ts

@@ -111,17 +111,18 @@ export interface ClientEncodedDelivery {
 }
 
 /**
- * Record the attempt's observed path: the request still goes through the internal Responses
- * bridge until the codecs decode to IR directly, so the request path and mode stay the bridge's;
- * the response now reaches the client from the IR without the internal Responses hop.
+ * Record the attempt's observed path. The response reaches the client from the IR without the
+ * internal Responses hop. The request side is the bridge's unless the ingress also decoded the
+ * conversation straight into the IR (the Antigravity direct lane, `requestLane: "direct"`).
  */
 function markDirectEncoderPath(logCtx: RequestLogContext, encoder: ClientEncoderOption, adapter: string): void {
   const attempt = logCtx.activeAttempt;
   if (!attempt) return;
   const upstream = upstreamWireForAdapter(attempt.adapter || adapter);
+  const lane = encoder.requestLane ?? "bridge";
   markAttemptProtocolPath(attempt, {
-    mode: deliveryModeForLane(encoder.protocol, "bridge", upstream),
-    requestPath: requestPathForLane(encoder.protocol, "bridge", upstream),
+    mode: deliveryModeForLane(encoder.protocol, lane, upstream),
+    requestPath: requestPathForLane(encoder.protocol, lane, upstream),
     responsePath: [upstream, "ir", encoder.protocol],
   });
 }

package/src/server/login-shell-path.ts

@@ -0,0 +1,146 @@
+/**
+ * The user's login-shell PATH, for installers the dashboard runs under OpenCodex Desktop (#6971).
+ *
+ * A Finder or login launch gives the Desktop app, and so its proxy sidecar, only the system PATH
+ * (`/usr/bin:/bin:/usr/sbin:/sbin`). `ocx codex-shim install` scans PATH for the native Codex
+ * launcher, so from the dashboard it reported "Native Codex launcher not found" for Homebrew, npm,
+ * bun, nvm, fnm, volta and mise installs, and an npm launcher had no `node` for its probe.
+ *
+ * This asks the user's shell once, as an interactive login shell would start, and keeps only PATH:
+ * the value is framed by markers so startup-file output cannot leak into it. The read has a
+ * deadline, runs in its own process group so a hung startup file is killed with all of its
+ * children, and its result, including failure, is cached so repeated dashboard actions do not
+ * spawn shells. It is scoped to the shim installer's child environment; the service definition's
+ * PATH has its own policy.
+ */
+import { spawn as nodeSpawn, type ChildProcess } from "node:child_process";
+import { userInfo } from "node:os";
+import { basename, isAbsolute } from "node:path";
+
+const BEGIN = "__OCX_LOGIN_PATH_BEGIN__";
+const END = "__OCX_LOGIN_PATH_END__";
+export const LOGIN_SHELL_PATH_TIMEOUT_MS = 5_000;
+export const LOGIN_SHELL_PATH_CACHE_MS = 5 * 60_000;
+const MAX_OUTPUT_BYTES = 64 * 1024;
+/** After the shell exits, how long its stdout may stay open before a background job is assumed to hold it. */
+const STDOUT_DRAIN_MS = 500;
+
+export function loginShellPathArgs(shell: string): string[] {
+  const print = basename(shell) === "fish"
+    ? `printf '%s%s%s\\n' ${BEGIN} (string join : $PATH) ${END}`
+    : `printf '%s%s%s\\n' ${BEGIN} "$PATH" ${END}`;
+  return ["-l", "-i", "-c", print];
+}
+
+/** The framed PATH, only when every entry is absolute. */
+export function parseLoginShellPath(output: string): string | null {
+  const start = output.lastIndexOf(BEGIN);
+  if (start < 0) return null;
+  const end = output.indexOf(END, start + BEGIN.length);
+  if (end < 0) return null;
+  const value = output.slice(start + BEGIN.length, end);
+  if (!value || /[\r\n\0]/.test(value)) return null;
+  const entries = value.split(":").filter(Boolean);
+  return entries.length > 0 && entries.every(entry => isAbsolute(entry)) ? entries.join(":") : null;
+}
+
+/** Ordered union: the shell's entries first, then any the process had that the shell did not. */
+export function mergePathLists(preferred: string, fallback: string | undefined): string {
+  // POSIX only: the login shell runs on macOS and Linux, where PATH is colon-separated.
+  return [...new Set([...preferred.split(":"), ...(fallback ?? "").split(":")].filter(Boolean))].join(":");
+}
+
+export interface LoginShellPathDeps {
+  platform?: NodeJS.Platform;
+  shell?: string | null;
+  env?: NodeJS.ProcessEnv;
+  spawn?: (command: string, args: string[], options: Parameters<typeof nodeSpawn>[2]) => ChildProcess;
+  killGroup?: (pid: number) => void;
+  timeoutMs?: number;
+  now?: () => number;
+}
+
+let cached: { at: number; value: string | null } | null = null;
+
+export function resetLoginShellPathCacheForTests(): void {
+  cached = null;
+}
+
+function defaultShell(env: NodeJS.ProcessEnv): string | null {
+  const fromEnv = env.SHELL?.trim();
+  if (fromEnv && isAbsolute(fromEnv)) return fromEnv;
+  try {
+    const shell = userInfo().shell;
+    return shell && isAbsolute(shell) ? shell : null;
+  } catch { return null; }
+}
+
+function killProcessGroup(pid: number): void {
+  try { process.kill(-pid, "SIGKILL"); } catch { /* already gone */ }
+}
+
+export async function readLoginShellPath(deps: LoginShellPathDeps = {}): Promise<string | null> {
+  const platform = deps.platform ?? process.platform;
+  if (platform === "win32") return null;
+  const now = deps.now ?? Date.now;
+  if (cached && now() - cached.at < LOGIN_SHELL_PATH_CACHE_MS) return cached.value;
+  const env = deps.env ?? process.env;
+  const shell = deps.shell === undefined ? defaultShell(env) : deps.shell;
+  const value = shell ? await probe(shell, env, deps) : null;
+  cached = { at: now(), value };
+  return value;
+}
+
+function probe(shell: string, env: NodeJS.ProcessEnv, deps: LoginShellPathDeps): Promise<string | null> {
+  const spawn = deps.spawn ?? nodeSpawn;
+  const killGroup = deps.killGroup ?? killProcessGroup;
+  return new Promise(resolve => {
+    let child: ChildProcess;
+    try {
+      child = spawn(shell, loginShellPathArgs(shell), {
+        detached: true,
+        stdio: ["ignore", "pipe", "ignore"],
+        // Only what a login shell needs to find its startup files; no proxy or credential state.
+        env: Object.fromEntries(Object.entries({
+          HOME: env.HOME, USER: env.USER, LOGNAME: env.LOGNAME, SHELL: shell, LANG: env.LANG,
+          PATH: env.PATH, TERM: "dumb",
+        }).filter(([, value]) => value !== undefined)) as NodeJS.ProcessEnv,
+      });
+    } catch { resolve(null); return; }
+    let output = "";
+    let settled = false;
+    let exitCode: number | null = null;
+    let drain: ReturnType<typeof setTimeout> | undefined;
+    const finish = (value: string | null, killGroupMembers: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(drain);
+      // A hung startup file, or a background job still holding the pipe, is killed with its group.
+      // A shell that exited and closed its output is left alone: its group id may already be free.
+      if (killGroupMembers && child.pid) killGroup(child.pid);
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(null, true), deps.timeoutMs ?? LOGIN_SHELL_PATH_TIMEOUT_MS);
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => {
+      output += chunk;
+      if (output.length > MAX_OUTPUT_BYTES) finish(null, true);
+    });
+    const parsed = () => exitCode === 0 ? parseLoginShellPath(output) : null;
+    child.once("error", () => finish(null, true));
+    // Parse only after stdout closes: `exit` can arrive before the last chunk.
+    child.once("close", code => { exitCode ??= code; finish(parsed(), false); });
+    child.once("exit", code => {
+      exitCode = code;
+      drain = setTimeout(() => finish(parsed(), true), STDOUT_DRAIN_MS);
+    });
+  });
+}
+
+/** `env` with the login-shell PATH in front, or unchanged when it cannot be read. */
+export async function withLoginShellPath(env: NodeJS.ProcessEnv, deps: LoginShellPathDeps = {}): Promise<NodeJS.ProcessEnv> {
+  const loginPath = await readLoginShellPath({ ...deps, env });
+  return loginPath ? { ...env, PATH: mergePathLists(loginPath, env.PATH) } : env;
+}
+