@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/server/configured-credentials.ts

@@ -0,0 +1,194 @@
+/**
+ * Credentials this installation is configured with, read when an upstream diagnostic is checked.
+ *
+ * A gateway can echo a credential it learned before this process ever sent it: an inactive pool
+ * key, another provider's key, an OAuth token from an earlier session. Learning only from sends
+ * would let such an echo be warned and finalized before the value is first dispatched, and a warning
+ * cannot be retracted. So the request log also refuses any diagnostic that repeats a configured
+ * value: every provider's apiKey and apiKeyPool keys (keychain and env references resolved), every
+ * configured header value, every credential-named provider field, and every token in the OAuth
+ * store. The set is rebuilt when the bytes of config.json or auth.json change, a stored keychain
+ * secret is replaced in this process, or a referenced environment variable changes.
+ *
+ * Freshness is decided by content, never by file metadata. Every check reads both stores and
+ * compares a digest of the bytes it read; the rebuild parses those same bytes. An inode/size/mtime
+ * key missed a same-length rewrite inside one timestamp tick (coarse on Windows) and any writer that
+ * preserves or backdates mtime, and then kept serving the previous, complete-looking view (#6923).
+ * The cost is two small reads per check; checks run only for retained upstream diagnostics.
+ *
+ * Reads are observe-only: no hardening, backup, repair or warning. A file that exists but cannot be
+ * read, parsed or recognized as the expected shape, or a keychain reference that cannot be resolved,
+ * makes coverage incomplete and callers fail closed; an incomplete set is retried after a short delay
+ * so a keychain that becomes available restores diagnostics. Values are held in memory only and
+ * never serialized or exposed.
+ *
+ * Not covered: keychain secrets are cached per process (`readKeychain` in
+ * src/providers/api-key-resolve.ts), so a secret replaced by another process is seen only after
+ * this process re-resolves it.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config/paths";
+import { resolveEnvValue } from "../config/proxy-env";
+import { isKeychainReference, providerKeyResolutionGeneration, resolveProviderApiKeyQuietly } from "../providers/api-key-resolve";
+import { credentialComponents, credentialSetMatches } from "../lib/outbound-credential-registry";
+import { SENSITIVE_KEY_PATTERN } from "../lib/redact";
+
+const CREDENTIAL_FIELD = /(?:key|token|secret|password|passwd|credential|cookie|authorization)$/i;
+/** How long an incomplete set is trusted before its sources are read again. */
+export const INCOMPLETE_RETRY_MS = 30_000;
+
+export interface ConfiguredCredentials {
+  readonly complete: boolean;
+  matches(value: string): boolean;
+}
+
+interface Snapshot {
+  /** The only object handed out: cache metadata (including env values) stays private here. */
+  readonly view: ConfiguredCredentials;
+  readonly signature: string;
+  readonly envNames: readonly string[];
+  readonly envFingerprint: string;
+  readonly builtAt: number;
+}
+
+let cached: Snapshot | undefined;
+
+/** One read of a store: its state for the signature and, for a readable file, the bytes read. */
+interface StoreRead {
+  /** "absent", "not-a-file", "unreadable", or "sha256:<hex>" of exactly the bytes in `text`. */
+  readonly state: string;
+  readonly text?: string;
+}
+
+function readStore(path: string): StoreRead {
+  try {
+    if (!statSync(path).isFile()) return { state: "not-a-file" };
+  } catch (error) {
+    // Only a store that is not there at all counts as intentionally absent.
+    return { state: (error as NodeJS.ErrnoException)?.code === "ENOENT" ? "absent" : "unreadable" };
+  }
+  let bytes: Buffer;
+  try {
+    bytes = readFileSync(path);
+  } catch {
+    // Present a moment ago, gone or unreadable now (a replacement in progress): fail closed.
+    return { state: "unreadable" };
+  }
+  return { state: `sha256:${createHash("sha256").update(bytes).digest("hex")}`, text: bytes.toString("utf8") };
+}
+
+function parseStore(read: StoreRead): { ok: boolean; value?: unknown } {
+  if (read.state === "absent") return { ok: true };
+  if (read.text === undefined) return { ok: false };
+  try {
+    return { ok: true, value: JSON.parse(read.text.replace(/^\uFEFF/, "")) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function envFingerprint(names: readonly string[]): string {
+  return names.map(name => process.env[name] ?? "\u0000unset").join("\u0000");
+}
+
+/** Mirrors resolveEnvValue: a braced or bare dollar reference reads the environment. */
+function envReference(raw: string): string | undefined {
+  if (!raw.startsWith("$")) return undefined;
+  return /^\$\{(\w+)\}$/.exec(raw)?.[1] ?? raw.slice(1);
+}
+
+function build(configRead: StoreRead, authRead: StoreRead, signature: string, now: number): Snapshot {
+  const values = new Set<string>();
+  const envNames = new Set<string>();
+  let complete = true;
+  const add = (raw: string | undefined) => {
+    if (raw) for (const part of credentialComponents(raw)) values.add(part);
+  };
+  const noteEnv = (raw: string) => {
+    const name = envReference(raw);
+    if (name) envNames.add(name);
+  };
+  const addReference = (raw: unknown) => {
+    if (typeof raw !== "string" || !raw) return;
+    noteEnv(raw);
+    const resolved = resolveProviderApiKeyQuietly(raw);
+    if (resolved === undefined && isKeychainReference(raw)) complete = false;
+    add(resolved);
+  };
+  const isCredentialField = (field: string) => CREDENTIAL_FIELD.test(field) || SENSITIVE_KEY_PATTERN.test(field);
+  const walkProvider = (node: unknown, depth: number) => {
+    if (depth > 8) return;
+    if (Array.isArray(node)) { for (const item of node) walkProvider(item, depth + 1); return; }
+    if (!isRecord(node)) return;
+    for (const [field, value] of Object.entries(node)) {
+      if (field === "headers" && isRecord(value)) {
+        for (const header of Object.values(value)) {
+          if (typeof header !== "string") continue;
+          noteEnv(header);
+          add(resolveEnvValue(header) ?? header);
+        }
+      } else if (typeof value === "string") {
+        if (isCredentialField(field)) addReference(value);
+      } else {
+        walkProvider(value, depth + 1);
+      }
+    }
+  };
+  const walkAuth = (node: unknown, depth: number) => {
+    if (depth > 8) return;
+    if (Array.isArray(node)) { for (const item of node) walkAuth(item, depth + 1); return; }
+    if (!isRecord(node)) return;
+    for (const [field, value] of Object.entries(node)) {
+      if (typeof value === "string") {
+        if (field === "access" || field === "refresh" || isCredentialField(field)) add(value);
+      } else {
+        walkAuth(value, depth + 1);
+      }
+    }
+  };
+
+  const configSig = configRead.state;
+  const authSig = authRead.state;
+  const config = parseStore(configRead);
+  const auth = parseStore(authRead);
+  if (!config.ok || !auth.ok) complete = false;
+  // An existing file must have the shape its loader expects; anything else hides credentials.
+  if (configSig !== "absent" && config.ok && (!isRecord(config.value)
+    || (config.value.providers !== undefined && !isRecord(config.value.providers)))) complete = false;
+  if (authSig !== "absent" && auth.ok && !isRecord(auth.value)) complete = false;
+  if (isRecord(config.value) && isRecord(config.value.providers)) walkProvider(config.value.providers, 0);
+  if (isRecord(auth.value)) walkAuth(auth.value, 0);
+
+  const names = [...envNames].sort();
+  const view: ConfiguredCredentials = Object.freeze({
+    complete,
+    matches: (value: string) => credentialSetMatches(values, candidate => values.has(candidate), value),
+  });
+  return {
+    view,
+    signature,
+    envNames: names,
+    envFingerprint: envFingerprint(names),
+    builtAt: now,
+  };
+}
+
+/** The configured credential set for the active config home, rebuilt when any input changes. */
+export function configuredCredentials(now = Date.now()): ConfiguredCredentials {
+  const dir = getConfigDir();
+  const configRead = readStore(join(dir, "config.json"));
+  const authRead = readStore(join(dir, "auth.json"));
+  const signature = `${configRead.state}|${authRead.state}|${providerKeyResolutionGeneration()}|${dir}`;
+  const stale = !cached
+    || cached.signature !== signature
+    || cached.envFingerprint !== envFingerprint(cached.envNames)
+    || (!cached.view.complete && now - cached.builtAt >= INCOMPLETE_RETRY_MS);
+  if (stale) cached = build(configRead, authRead, signature, now);
+  return cached!.view;
+}

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/link-management.ts

@@ -0,0 +1,58 @@
+/**
+ * The Home end of the Remote Link management relay (#6957).
+ *
+ * Reached only on the hub-link listener, after the request has passed its link-key admission
+ * (`resolveApiAuth` restricted to recorded link keys) and the shared route table in
+ * `src/link/management-routes.ts`. The management handler sees a fresh request built here: no
+ * caller header, cookie, Origin or credential crosses from the link, and the principal is
+ * absent, so no consent- or capability-gated branch can be reached. Only allowlisted reads run.
+ * They run as passive reads (`src/lib/passive-read.ts`): no discovery, config write or diagnostic (#6959).
+ */
+import type { OcxConfig } from "../../types";
+import { handleManagementAPI, type ManagementApiDeps } from "../management-api";
+import type { ManagementSessionControl } from "../management-auth";
+import { runPassiveRead } from "../../lib/passive-read";
+import { LINK_CODEX_SETTINGS_PATH, linkManagementRouteAllowed, linkManagementTarget } from "../../link/management-routes";
+import { projectHomeCodexSettings } from "../../link/codex-settings";
+import { packageVersion } from "../../lib/package-version";
+
+const VERSION = packageVersion("0.0.0");
+const KEPT_RESPONSE_HEADERS = ["content-type", "content-language", "etag", "last-modified"];
+
+function notFound(): Response {
+  return Response.json({ error: "not_found" }, { status: 404, headers: { "cache-control": "no-store" } });
+}
+
+export async function handleLinkManagementRequest(
+  req: Request,
+  url: URL,
+  config: OcxConfig,
+  deps: ManagementApiDeps,
+  sessionControl?: ManagementSessionControl,
+): Promise<Response> {
+  if (!linkManagementRouteAllowed(url, req)) return notFound();
+  if (url.pathname === LINK_CODEX_SETTINGS_PATH) {
+    return Response.json(projectHomeCodexSettings(config, VERSION), { headers: { "cache-control": "no-store" } });
+  }
+  const target = linkManagementTarget(url);
+  if (!target) return notFound();
+  const local = new URL(`${target.pathname}${target.search}`, "http://127.0.0.1");
+  // The handlers branch on GET; an admitted HEAD runs as GET and its body is dropped below.
+  const inner = new Request(local.href, {
+    method: "GET",
+    headers: { accept: "application/json", host: "127.0.0.1" },
+  });
+  const response = await runPassiveRead(() =>
+    handleManagementAPI(inner, local, config, deps, undefined, sessionControl, { trustedLoopback: false }));
+  if (!response) return notFound();
+  const headers = new Headers({ "cache-control": "no-store" });
+  for (const name of KEPT_RESPONSE_HEADERS) {
+    const value = response.headers.get(name);
+    if (value) headers.set(name, value);
+  }
+  if (req.method === "HEAD") {
+    try { await response.body?.cancel(); } catch { /* best effort */ }
+    return new Response(null, { status: response.status, headers });
+  }
+  return new Response(response.body, { status: response.status, headers });
+}

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

@@ -14,6 +14,7 @@ import {
   type LinkListenerStatus,
 } from "./link-listener";
 import { createLinkSupervisor, type LinkSupervisor } from "../../link/supervisor";
+import { linkManagementRouteAllowed } from "../../link/management-routes";
 import { saveConfigPreservingClaudeCode } from "../../config/live-reconcile";
 import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
 export { LINK_INGRESS_HOSTNAME } from "./link-listener";
@@ -77,7 +78,10 @@ export function createOptionalListenerSet<T>(linkDeps: LinkListenerDeps = {}): O
       if (claudeIntercept.ownsListener(server)) return "claude-intercept";
       return undefined;
     },
-    linkRouteAllowed,
+    // The Home's link listener admits the data plane plus the read-only management relay
+    // (#6957). The Child's own ingress keeps the data-only table, so a local caller on the Child
+    // cannot reach the Home's management reads without the Child's dashboard session.
+    linkRouteAllowed: (url, req) => linkRouteAllowed(url, req) || linkManagementRouteAllowed(url, req),
     linkAdmissionKeyIds: () => linkListener.linkAdmissionKeyIds(),
     onAuthenticatedCatalog: listener => linkListener.onAuthenticatedCatalog(listener),
     notifyAuthenticatedCatalog: apiKeyId => linkListener.notifyAuthenticatedCatalog(apiKeyId),

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

@@ -1,5 +1,6 @@
 import type { Server, ServerWebSocket } from "bun";
 import type { StartServerDeps } from "./startup-warnings";
+import { isLinkManagementPath } from "../../link/management-routes";
 import {
   GUI_PAIRING_EXCHANGE_BODY_LIMIT,
   REMOTE_WORKSPACE_PAIRING_BODY_LIMIT,
@@ -96,6 +97,7 @@ import {
   isAllowedManagementOrigin,
   isApiAuthRequired,
   isLoopbackHostname,
+  markTrustedHubManagementRequest,
   jsonResponse,
   admissionFields,
   resolveApiAuth,
@@ -313,6 +315,11 @@ export function createServeOptions(ctx: ServeOptionsContext) {
       maxRequestBodySize: inboundBodyLimitBytes,
       async fetch(req: Request, requestServer: Server<WsData>): Promise<Response> {
       const ingress = ingressForServer(requestServer);
+      // Bind management-origin trust to the actual Bun listener object resolved above.
+      // Neither Host nor any X-Forwarded-* header can manufacture this process-local mark.
+      if (ingress === "hub-management" && config.runtimeRole === "hub") {
+        markTrustedHubManagementRequest(req);
+      }
       const requestUrl = codexCompatibleUrl(req.url);
       const linkPolicyView = ingress === "hub-link" ? linkPolicy() : undefined;
       // The unauthenticated loopback listener (#1102) serves a fixed allowlist and nothing
@@ -367,6 +374,12 @@ export function createServeOptions(ctx: ServeOptionsContext) {
         if (requestUrl.pathname === "/v1/catalog" && requestUrl.search === ""
           && (req.method === "GET" || req.method === "HEAD")
           && admission.kind === "configured") onAuthenticatedCatalog(admission.keyId);
+        // #6957: the Child's read-only view of this Home. Admitted by the link key above and by
+        // the shared table in src/link/management-routes.ts; never reachable on another ingress.
+        if (isLinkManagementPath(requestUrl.pathname)) {
+          const { handleLinkManagementRequest } = await import("./link-management");
+          return withCors(await handleLinkManagementRequest(req, requestUrl, config, requestManagementApiDeps, managementSessionControl), req, policy);
+        }
       }
       const url = requestUrl;
       const admissionOptions = { linkIngress: policy.linkIngress?.allowedKeyIds };
@@ -1042,7 +1055,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
@@ -1058,7 +1071,7 @@ export function createServeOptions(ctx: ServeOptionsContext) {
             goOrdered,
             resolveAutoContext(config.claudeCode),
             idStyle,
-            activeDesktop3pAlias,
+            resolvableDesktop3pAlias,
             desktopInputs.nativeContextCap,
             config.fastMode,
             // Explicit opt-out omits the Fast predicate.

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

@@ -277,3 +277,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 = () => {
@@ -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/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/lifecycle.ts

@@ -8,7 +8,7 @@ import {
 } from "../storage/policy-job";
 import { abortRestoreTrashJobAsync } from "../storage/restore-job";
 import { stopStorageCleanupScheduler } from "../storage/policy-scheduler";
-import { runOptionalShutdownHooks } from "../lib/optional-shutdown-hooks";
+import { runDrainStartHooks, runOptionalShutdownHooks } from "../lib/optional-shutdown-hooks";
 import { stopStateStoreSweeper } from "../lib/state-store-sweeper";
 import {
   cancelQueuedStorageWorkerSpawns,
@@ -499,6 +499,7 @@ export async function drainAndShutdown(
   // ordinary in-flight turns. A stuck scoped owner must not pin shutdown forever.
   const deadline = Date.now() + Math.max(0, timeoutMs);
   beginShutdownDrain();
+  runDrainStartHooks();
   const temporaryDrainsSettled = await waitForTemporaryDrainsUntil(deadline);
   if (!temporaryDrainsSettled) {
     console.warn("Temporary drain lease did not settle before the shutdown deadline; forcing shutdown");