@bitkyc08/opencodex 2.65.0 → 2.66.0-preview.20260925

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

@@ -0,0 +1,235 @@
+/**
+ * Adapter delivery straight into a Chat or Messages client's wire (PF-09).
+ *
+ * The streaming adapter branch normally bridges the guarded event stream into Responses SSE and
+ * lets the ingress convert that into the client's wire. With a `clientEncoder` option the same
+ * events are encoded directly instead; everything the bridge did besides framing keeps happening:
+ *
+ * - the events are also collected, charged to the request's translator budget, and folded with
+ *   `buildResponseJSON` at the terminal, so the replay caches, `rememberResponseState`,
+ *   `notifyResponseComplete` and `commitReasoningReplayServingRoute` see a completed response
+ *   exactly when the bridge's `onCompletedResponse` would have fired;
+ * - the key-usage binding receives the adapter usage under the bridge's rules;
+ * - the stream is tracked for turn lifetime and stops the upstream the same way;
+ * - the request log receives the facts its Responses SSE tap used to read (client-wire.ts).
+ */
+import type { AdapterEvent, OcxConfig, OcxProviderContinuationState, OcxReasoningReplayScopeRef, OcxUsage } from "../../types";
+import type { AdmissionLease } from "../../lib/admission";
+import {
+  releaseTranslatedEvent,
+  retainTranslatedEvent,
+  type TranslatorBudget,
+} from "../../lib/translator-budget";
+import { buildResponseJSON } from "../../bridge";
+import { responsesUsage, uuid } from "../../bridge/internal";
+import { awaitThoughtSignatureDurability } from "../../responses/thought-signature-replay";
+import { attemptDeliveryRecorder } from "../../usage/attempt-delivery";
+import { encodeChatCompletionSse, collectChatCompletionResponse } from "../../protocols/encoders/chat";
+import { encodeAnthropicMessageSse, collectAnthropicMessageResponse } from "../../protocols/encoders/messages";
+import type { ClientEncodeHooks, EncodedTerminal } from "../../protocols/encoders/adapter-events";
+import { upstreamWireForAdapter } from "../../protocols/contract";
+import { markAttemptProtocolPath } from "../../protocols/trace";
+import { deliveryModeForLane, requestPathForLane } from "../../protocols/path";
+import { resolveProtocolSettings } from "../../protocols/settings";
+import { trackStreamLifetime } from "../lifecycle";
+import type { RequestLogContext } from "../request-log";
+import type { ClientEncoderOption, HandleResponsesOptions } from "../responses/core-options";
+import { attachClientWireLog, createClientWireLog, markClientWire } from "./client-wire";
+
+const CLIENT_SSE_HEADERS = {
+  "Content-Type": "text/event-stream; charset=utf-8",
+  "Cache-Control": "no-cache",
+  Connection: "keep-alive",
+} as const;
+
+/**
+ * Whether a Chat or Messages ingress asks for direct encoding on the route it settled: the
+ * rollout switch is on and the route is one concrete non-Responses target. Combo and policy
+ * routes read or retry the Responses body after delivery, and a Responses-wire route is the
+ * passthrough case this work leaves alone.
+ */
+export function directEncodersApply(
+  config: Pick<OcxConfig, "protocols">,
+  route: { combo?: unknown; routeKind?: string; provider: { adapter: string } } | null | undefined,
+): boolean {
+  if (!route || !resolveProtocolSettings(config).rollout.directEncoders) return false;
+  if (route.combo !== undefined || route.routeKind === "policy") return false;
+  return upstreamWireForAdapter(route.provider.adapter) !== "responses";
+}
+
+/**
+ * The encoder this delivery may use, or undefined to keep the Responses body. The final route
+ * is re-checked because core can still change it after the ingress decided: a combo child's
+ * body is read by the combo's commit logic, a policy route may hop on an error body, a
+ * compaction turn must emit its synthetic item, and a Responses-wire upstream stays as it is.
+ */
+export function clientEncoderForDelivery(
+  options: Pick<HandleResponsesOptions, "clientEncoder" | "comboAttempt">,
+  logCtx: Pick<RequestLogContext, "routeDecision">,
+  routedCompaction: boolean,
+  adapterName: string,
+): ClientEncoderOption | undefined {
+  const encoder = options.clientEncoder;
+  if (!encoder || options.comboAttempt || routedCompaction) return undefined;
+  if (logCtx.routeDecision?.routeKind === "policy" || logCtx.routeDecision?.routeKind === "combo") return undefined;
+  if (upstreamWireForAdapter(adapterName) === "responses") return undefined;
+  return encoder;
+}
+
+export interface ClientEncodedDelivery {
+  encoder: ClientEncoderOption;
+  events: AsyncIterable<AdapterEvent>;
+  logCtx: RequestLogContext;
+  translatorBudget: TranslatorBudget;
+  /** Model on the folded response and the log payloads, as on the bridge's snapshots. */
+  responseModelId: string;
+  adapterName: string;
+  fold: {
+    replayCacheScope?: OcxReasoningReplayScopeRef;
+    hideThinkingSummary?: boolean;
+    toolNsMap?: Map<string, { namespace: string; name: string; freeform?: true }>;
+    declaredToolNames?: ReadonlySet<string>;
+    toolParameterSchemas?: ReadonlyMap<string, Record<string, unknown>>;
+    freeformToolNames?: Set<string>;
+    toolSearchToolNames?: Set<string>;
+  };
+  stallTimeoutSec?: number;
+  turnAdmissionLease?: AdmissionLease;
+  onFirstOutput?: () => void;
+  /** The bridge's `onCancel`: stop completion notification and abort the upstream. */
+  stopUpstream: () => void;
+  /** Turn-lifetime cleanup when the client body finishes or is cancelled. */
+  onStreamDone: () => void;
+  /** The bridge's `onCompletedResponse`, fed the folded response. */
+  onCompletedResponse: (response: Record<string, unknown>, providerState?: OcxProviderContinuationState) => void;
+  /** The bridge's `onUsage`. */
+  bindUsage: (usage: OcxUsage | undefined) => void;
+}
+
+/**
+ * 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.
+ */
+function markDirectEncoderPath(logCtx: RequestLogContext, encoder: ClientEncoderOption, adapter: string): void {
+  const attempt = logCtx.activeAttempt;
+  if (!attempt) return;
+  const upstream = upstreamWireForAdapter(attempt.adapter || adapter);
+  markAttemptProtocolPath(attempt, {
+    mode: deliveryModeForLane(encoder.protocol, "bridge", upstream),
+    requestPath: requestPathForLane(encoder.protocol, "bridge", upstream),
+    responsePath: [upstream, "ir", encoder.protocol],
+  });
+}
+
+export async function deliverClientEncodedResponse(input: ClientEncodedDelivery): Promise<Response> {
+  const { encoder, logCtx, translatorBudget } = input;
+  markDirectEncoderPath(logCtx, encoder, input.adapterName);
+  const log = createClientWireLog();
+  const responseId = `resp_${uuid()}`;
+  const createdAt = Math.floor(Date.now() / 1000);
+  const snapshot = (status: string): Record<string, unknown> => ({
+    id: responseId, object: "response", created_at: createdAt,
+    status, model: input.responseModelId, output: [], usage: null,
+  });
+  log.record({ kind: "observe", payload: { type: "response.created", response: snapshot("in_progress") } });
+
+  // Collected copies: the adapter's own objects may already carry a lease from a buffered batch.
+  const collected: AdapterEvent[] = [];
+  let sealed = false;
+  const releaseCollected = () => {
+    sealed = true;
+    for (const event of collected) releaseTranslatedEvent(event, translatorBudget);
+    collected.length = 0;
+  };
+  const events = (async function* (): AsyncGenerator<AdapterEvent> {
+    for await (const event of input.events) {
+      if (!sealed) {
+        const copy = { ...event } as AdapterEvent;
+        retainTranslatedEvent(copy, translatorBudget, collected.at(-1));
+        collected.push(copy);
+      }
+      yield event;
+    }
+  })();
+  const fold = (): Record<string, unknown> | undefined => {
+    if (sealed) return undefined;
+    sealed = true;
+    try {
+      return buildResponseJSON(collected, input.responseModelId, {
+        ...input.fold,
+        enforceDeclaredToolNames: false,
+        translatorBudget,
+        recordBufferedDelivery: false,
+      });
+    } catch {
+      return undefined;
+    } finally {
+      releaseCollected();
+    }
+  };
+
+  const recorder = attemptDeliveryRecorder(translatorBudget);
+  let completedResponseDelivered = false;
+  const terminalPayload = (terminal: EncodedTerminal): Record<string, unknown> => ({
+    type: terminal.status === "completed" ? "response.completed"
+      : terminal.status === "failed" ? "response.failed"
+      : "response.incomplete",
+    response: {
+      ...snapshot(terminal.status),
+      ...(terminal.endTurn !== undefined ? { end_turn: terminal.endTurn } : {}),
+      usage: terminal.usageOnWire ? responsesUsage(terminal.usage) : null,
+      ...(terminal.incomplete ? { incomplete_details: { ...terminal.incomplete } } : {}),
+      ...(terminal.error ? { error: terminal.error, last_error: terminal.error } : {}),
+      ...(terminal.retryable !== undefined ? { retryable: terminal.retryable } : {}),
+    },
+  });
+  const hooks: ClientEncodeHooks = {
+    ...(input.onFirstOutput ? { onFirstOutput: input.onFirstOutput } : {}),
+    async beforeTerminal(terminal) {
+      const response = terminal.overflow ? (releaseCollected(), undefined) : fold();
+      if (terminal.durable) await awaitThoughtSignatureDurability();
+      if (terminal.completedResponse && response && !completedResponseDelivered) {
+        completedResponseDelivered = true;
+        input.onCompletedResponse(response, terminal.providerState);
+      }
+      if (terminal.reportUsage) input.bindUsage(terminal.usage);
+    },
+    afterTerminal(terminal) {
+      log.record({ kind: "terminal", status: terminal.status, payload: terminalPayload(terminal) });
+    },
+    stopUpstream: input.stopUpstream,
+    onClientCancel() {
+      releaseCollected();
+      log.record({ kind: "cancel" });
+    },
+    onRelayed(observation) {
+      recorder?.noteRelayedEvent(observation);
+    },
+  };
+  const encodeOptions = {
+    model: encoder.model,
+    translatorBudget,
+    ...input.fold,
+    ...(input.stallTimeoutSec !== undefined ? { stallTimeoutSec: input.stallTimeoutSec } : {}),
+    hooks,
+  };
+  const encoded = encoder.protocol === "chat"
+    ? encodeChatCompletionSse(events, encodeOptions)
+    : encodeAnthropicMessageSse(events, {
+      ...encodeOptions,
+      ...(encoder.inputTokenFloor !== undefined ? { inputTokenFloor: encoder.inputTokenFloor } : {}),
+    });
+  const tracked = trackStreamLifetime(encoded, new AbortController(), input.onStreamDone, input.turnAdmissionLease);
+
+  let response: Response;
+  if (encoder.stream) {
+    response = new Response(tracked, { status: 200, headers: CLIENT_SSE_HEADERS });
+  } else {
+    // The routed turn always streams internally; a non-streaming client gets the fold.
+    response = encoder.protocol === "chat"
+      ? await collectChatCompletionResponse(tracked, encoder.model, translatorBudget)
+      : await collectAnthropicMessageResponse(tracked, encoder.model, translatorBudget);
+  }
+  return attachClientWireLog(markClientWire(response, encoder.protocol), log);
+}

package/src/server/inference/client-wire-log.ts

@@ -0,0 +1,49 @@
+import {
+  addFinalRequestLog,
+  httpStatusForRequestLogTerminal,
+  inspectResponseLogSsePayloadParsed,
+  type RequestLogContext,
+  type RequestLogEntry,
+} from "../request-log";
+import type { ClientWireLog } from "./client-wire";
+
+/**
+ * The deferred request log of a client-wire response. It records what the Responses SSE tap
+ * (`trackSseForRequestLog`) records for a bridged body, from the facts the producer reports
+ * instead of from the body: the same payload inspection until the terminal, the same terminal
+ * transport phase and status mapping, and 499 for a client cancel before any terminal. The row
+ * is written once.
+ */
+export function recordClientWireRequestLog(
+  log: ClientWireLog,
+  requestId: string,
+  start: number,
+  logCtx: RequestLogContext,
+  addLog: (entry: RequestLogEntry) => void,
+): void {
+  let logged = false;
+  const inspect = (payload: Record<string, unknown>) => {
+    try {
+      inspectResponseLogSsePayloadParsed(logCtx, JSON.stringify(payload), payload);
+    } catch { /* request log metadata is best-effort */ }
+  };
+  log.subscribe(event => {
+    if (logged) return;
+    if (event.kind === "observe") {
+      inspect(event.payload);
+      return;
+    }
+    logged = true;
+    if (event.kind === "cancel") {
+      addFinalRequestLog(requestId, start, logCtx, 499, { closeReason: "client_cancel" }, addLog);
+      return;
+    }
+    inspect(event.payload);
+    logCtx.transportPhase = "terminal_sse";
+    logCtx.terminalSource = "upstream";
+    addFinalRequestLog(requestId, start, logCtx, httpStatusForRequestLogTerminal(event.status, logCtx), {
+      terminalStatus: event.status,
+      closeReason: "terminal",
+    }, addLog);
+  });
+}

package/src/server/inference/client-wire.ts

@@ -0,0 +1,69 @@
+import type { Protocol } from "../../protocols/contract";
+
+const clientWires = new WeakMap<Response, Protocol>();
+
+/**
+ * Record that `response` is already in `protocol`'s client wire, so an ingress can tell a body
+ * it may pass through from a Responses body it still has to convert. Identity-keyed: a
+ * rebuilt or cloned Response carries no mark. Returns the same response.
+ */
+export function markClientWire(response: Response, protocol: Protocol): Response {
+  clientWires.set(response, protocol);
+  return response;
+}
+
+/** The client wire `response` was marked with, or undefined for an unmarked response. */
+export function clientWireOf(response: Response): Protocol | undefined {
+  return clientWires.get(response);
+}
+
+/** What the request log of a client-wire response learns, in the order the stream learned it. */
+export type ClientWireLogEvent =
+  /** A Responses-vocabulary payload the legacy log tap would have inspected. */
+  | { kind: "observe"; payload: Record<string, unknown> }
+  | { kind: "terminal"; status: "completed" | "failed" | "incomplete"; payload: Record<string, unknown> }
+  | { kind: "cancel" };
+
+/**
+ * A client-wire body cannot be tapped for the request log the way a Responses body is: its
+ * frames are not Responses events. The producer records the facts the tap would have read, and
+ * the deferred request log subscribes. Events recorded before the subscription are replayed to
+ * it; the producer records at most a start payload, one terminal and one cancel.
+ */
+export interface ClientWireLog {
+  record(event: ClientWireLogEvent): void;
+  subscribe(listener: (event: ClientWireLogEvent) => void): void;
+}
+
+export function createClientWireLog(): ClientWireLog {
+  let pending: ClientWireLogEvent[] | undefined = [];
+  let listener: ((event: ClientWireLogEvent) => void) | undefined;
+  const deliver = (event: ClientWireLogEvent) => {
+    try { listener?.(event); } catch { /* logging never throws into the stream */ }
+  };
+  return {
+    record(event) {
+      if (pending) pending.push(event);
+      else deliver(event);
+    },
+    subscribe(next) {
+      if (listener) return;
+      listener = next;
+      const buffered = pending ?? [];
+      pending = undefined;
+      for (const event of buffered) deliver(event);
+    },
+  };
+}
+
+const clientWireLogs = new WeakMap<Response, ClientWireLog>();
+
+/** Attach the log channel a client-wire response reports through. Returns the same response. */
+export function attachClientWireLog(response: Response, log: ClientWireLog): Response {
+  clientWireLogs.set(response, log);
+  return response;
+}
+
+export function clientWireLogOf(response: Response): ClientWireLog | undefined {
+  return clientWireLogs.get(response);
+}

package/src/server/inference/context.ts

@@ -0,0 +1,15 @@
+import { createRequestExecutionBudget, type RequestExecutionBudget } from "../../lib/request-execution-budget";
+import type { RequestLogContext } from "../request-log";
+import { attachRequestSpendTracker } from "../responses/request-spend";
+
+/**
+ * The one construction of an ingress-owned send budget: the default guarded policy, no logical
+ * request id, and this request's spend tracker as the send observer. Attaching the tracker
+ * parks it on `logCtx`, so callers that inherit a holder must not call this at all.
+ */
+export function createInferenceSendBudget(
+  req: Pick<Request, "headers">,
+  logCtx: RequestLogContext,
+): RequestExecutionBudget {
+  return createRequestExecutionBudget(undefined, undefined, attachRequestSpendTracker(req, logCtx));
+}

package/src/server/inference/final-log.ts

@@ -0,0 +1,37 @@
+import { addFinalRequestLog, type RequestLogContext, type RequestLogEntry } from "../request-log";
+
+/** The request-row identity an ingress hands down; absent when nothing records the request. */
+export interface FinalRequestLogIds {
+  requestId: string;
+  start: number;
+}
+
+export type FinalRequestLogMeta = Pick<RequestLogEntry, "terminalStatus" | "closeReason">;
+
+export interface FinalRequestLog {
+  /** Write the final request row once. Every later call, from any path, is a no-op. */
+  finish(status: number, meta?: FinalRequestLogMeta): void;
+  /** True once `finish` has run, whether or not a row was written. */
+  finished(): boolean;
+}
+
+/**
+ * Finish-once ownership of one request's final log row. Terminal callbacks, cancellation and
+ * the non-stream return race each other, and only the first of them may write the row.
+ * Without log ids the claim still settles, so a caller's `finished()` check behaves the same
+ * whether or not the request is recorded.
+ */
+export function createFinalRequestLog(
+  logIds: FinalRequestLogIds | undefined,
+  logCtx: RequestLogContext,
+): FinalRequestLog {
+  let done = false;
+  return {
+    finish: (status, meta) => {
+      if (done) return;
+      done = true;
+      if (logIds) addFinalRequestLog(logIds.requestId, logIds.start, logCtx, status, meta);
+    },
+    finished: () => done,
+  };
+}

package/src/server/local-desktop-snapshot-auth.ts

@@ -0,0 +1,57 @@
+import { timingSafeEqual } from "node:crypto";
+import {
+  LOCAL_MANAGEMENT_CAPABILITY_EXPIRES_AT_HEADER,
+  LOCAL_MANAGEMENT_CAPABILITY_HEADER,
+  LOCAL_MANAGEMENT_EXPECTED_PID_HEADER,
+  LOCAL_MANAGEMENT_NONCE_HEADER,
+  parseExpectedLocalManagementPid,
+} from "../lib/local-management-capability";
+import {
+  desktopSnapshotBodyDigest,
+  LOCAL_DESKTOP_SNAPSHOT_BODY_HEADER,
+  LOCAL_DESKTOP_SNAPSHOT_PATH,
+  verifyLocalDesktopSnapshotCapability,
+} from "../lib/local-desktop-snapshot-capability";
+import type { LocalManagementAuthContext } from "./management-auth";
+
+const REPLAY_LIMIT = 256;
+const consumed = new Map<string, number>();
+const admittedBodyDigests = new WeakMap<Request, string>();
+
+/** Admit only the snapshot POST; a grant never becomes a general management credential. */
+export function hasLocalDesktopSnapshotCapability(
+  req: Request,
+  local: LocalManagementAuthContext | undefined,
+  now = Date.now(),
+): boolean {
+  if (admittedBodyDigests.has(req)) return true;
+  if (!local || req.method !== "POST" || req.headers.has("origin")) return false;
+  let url: URL;
+  try { url = new URL(req.url); } catch { return false; }
+  if (url.pathname !== LOCAL_DESKTOP_SNAPSHOT_PATH || url.search !== "") return false;
+  const expectedPid = parseExpectedLocalManagementPid(req.headers.get(LOCAL_MANAGEMENT_EXPECTED_PID_HEADER));
+  if (expectedPid.kind !== "present" || expectedPid.pid !== local.pid) return false;
+  const expiry = req.headers.get(LOCAL_MANAGEMENT_CAPABILITY_EXPIRES_AT_HEADER);
+  if (!expiry || !/^[1-9]\d*$/.test(expiry)) return false;
+  const expiresAt = Number(expiry);
+  const capability = req.headers.get(LOCAL_MANAGEMENT_CAPABILITY_HEADER);
+  const bodyDigest = req.headers.get(LOCAL_DESKTOP_SNAPSHOT_BODY_HEADER);
+  if (!verifyLocalDesktopSnapshotCapability(
+    local.attestationSecret, req.headers.get(LOCAL_MANAGEMENT_NONCE_HEADER),
+    req.method, url.pathname, local.pid, local.port, expiresAt, bodyDigest, capability, now,
+  )) return false;
+  for (const [proof, until] of consumed) if (until <= now) consumed.delete(proof);
+  if (!capability || !bodyDigest || consumed.has(capability) || consumed.size >= REPLAY_LIMIT) return false;
+  consumed.set(capability, expiresAt);
+  // Cache the authenticated digest, not a mutable header. The route must verify
+  // its bounded raw body against this value before it changes display state.
+  admittedBodyDigests.set(req, bodyDigest);
+  return true;
+}
+
+/** Finish admission after the route has read at most 1 KiB, before parsing or storing JSON. */
+export function verifyLocalDesktopSnapshotBody(req: Request, body: Uint8Array): boolean {
+  const expected = admittedBodyDigests.get(req);
+  if (!expected || body.byteLength > 1024) return false;
+  return timingSafeEqual(Buffer.from(expected), Buffer.from(desktopSnapshotBodyDigest(body)));
+}

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

@@ -1405,7 +1405,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     const models = await fetchAllModels(config);
     const { listCatalogNativeSlugs } = await import("../../codex/catalog");
     const { claudeCodeAlias, claudeCodeNativeAlias } = await import("../../claude/alias");
-    const { buildClaudeContextWindows, effectiveModelEnv } = await import("../../claude/context-windows");
+    const { buildClaudeContextWindows, effectiveModelEnv, nativeClaudePassthroughFor } = await import("../../claude/context-windows");
     const { visibleNativeSlugs } = await import("../../codex/catalog");
     const disabled = new Set(config.disabledModels ?? []);
     const isDisabled = (provider: string, id: string) =>
@@ -1432,9 +1432,6 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       const listedId = (m.provider === "cursor" ? cursorFastIdFor?.(m.id) : undefined) ?? m.id;
       aliases.push({ id: claudeCodeAlias(m.provider, listedId), display_name: `${listedId} (${m.provider})` });
     }
-    const contextWindows = buildClaudeContextWindows([...visibleNativeSlugs(config)], models, nativeContextLimits(config));
-    const webSearchOverride = config.claudeCode?.webSearchSidecar;
-    const visionOverride = config.claudeCode?.visionSidecar;
     // Auto is a RESOLUTION, recomputed per request — never stored state. Detection is
     // daemon-side, so it cannot see a key exported only in the user's terminal; the
     // GUI labels the badge with detectionScope for exactly that reason.
@@ -1442,6 +1439,14 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     const { authModeIntent, resolveClaudeAuthMode } = await import("../../claude/auth-mode");
     const authDetection = detectClaudeAuth(defaultAuthDetectDeps(process.env, ownAdmissionTokens(config)));
     const resolvedAuthMode = resolveClaudeAuthMode(config, authDetection);
+    const contextWindows = buildClaudeContextWindows(
+      [...visibleNativeSlugs(config)],
+      models,
+      nativeContextLimits(config),
+      nativeClaudePassthroughFor(config.claudeCode, resolvedAuthMode.markerMode),
+    );
+    const webSearchOverride = config.claudeCode?.webSearchSidecar;
+    const visionOverride = config.claudeCode?.visionSidecar;
     return jsonResponse({
       enabled: config.claudeCode?.enabled !== false,
       // Three-state intent (devlog 260726_claude_auth_auto): an absent key is AUTO, not
@@ -1740,15 +1745,12 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       }
     }
     if (body.fastMode !== undefined) config.fastMode = nextFastMode;
-    config.claudeCode = next;
-    // Stamp the migration sentinel on EVERY persist of this block. The migration reads
-    // "a claudeCode block with no authMode" as a pre-upgrade subscriber and pins it to
-    // literal subscription — correct for a config written before `auto` existed, fatal
-    // for one written after. Without this, choosing Auto (which DELETES authMode) or
-    // merely toggling Claude on (App.tsx PUTs `{enabled}` alone and creates the block)
-    // would be converted into a sticky manual subscription by the next startServer, and
-    // auto would survive exactly one proxy lifetime with no way back.
-    if (!next.authModeMigratedAt) next.authModeMigratedAt = new Date().toISOString();
+    // Stamps the auth-mode migration sentinel on EVERY persist of this block. Without it,
+    // choosing Auto (which DELETES authMode) or merely toggling Claude on (App.tsx PUTs
+    // `{enabled}` alone and creates the block) would be converted into a sticky manual
+    // subscription by the next startServer, with no way back.
+    const { commitClaudeCodeBlock } = await import("../../claude/claude-code-block");
+    commitClaudeCodeBlock(config, next);
     const { saveConfigPreservingClaudeCode: save } = await import("../../config");
     save(config);
     const warnings: string[] = [];

package/src/server/management/api-access.ts

@@ -3,6 +3,7 @@ import { isWildcardHostname } from "../../codex/loopback-target";
 import { localCredentialDestinationHostname, localInferenceDestination } from "../../lib/local-destinations";
 import { isCanonicalOpenAiForwardProvider, OPENAI_API_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers-destination";
 import { LIVE_AUDIO_MODEL, TRANSCRIPTION_MODEL } from "../audio-upstream";
+import { resolveApiSurfaceSettings, type ApiSurfaceSettings } from "../../protocols/settings";
 
 export interface AudioApiAccess {
   transcriptionEndpoint: string;
@@ -23,6 +24,13 @@ export interface ApiAccessEndpoints {
   chatCompletionsEndpoint: string;
   messagesEndpoint: string;
   modelsEndpoint: string;
+  /** Which public APIs are served and who decided it, from `resolveApiSurfaceSettings`. */
+  surfaces: ApiSurfaceSettings;
+  /**
+   * Back-compat for dashboards that predate `surfaces`: they hide the Messages endpoint when
+   * this is false. It mirrors `surfaces.messages.enabled`, not `claudeCode.enabled`, so an
+   * older dashboard never advertises a closed endpoint or hides an open one.
+   */
   claudeCodeEnabled: boolean;
   audio: AudioApiAccess;
   /** Back-compat alias for older GUI clients. */
@@ -165,13 +173,15 @@ export function buildApiAccessEndpoints(
   const apiConfigured = !!keyed && keyed.disabled !== true && keyed.adapter === "openai-responses"
     && keyed.authMode !== "forward" && keyed.baseUrl.replace(/\/+$/, "") === "https://api.openai.com/v1"
     && typeof keyed.apiKey === "string" && !!keyed.apiKey.trim();
+  const surfaces = resolveApiSurfaceSettings(config);
   return {
     baseUrl,
     responsesEndpoint,
     chatCompletionsEndpoint: `${baseUrl}/chat/completions`,
     messagesEndpoint: `${baseUrl}/messages`,
     modelsEndpoint: `${baseUrl}/models`,
-    claudeCodeEnabled: config.claudeCode?.enabled !== false,
+    surfaces,
+    claudeCodeEnabled: surfaces.messages.enabled,
     audio: {
       transcriptionEndpoint: `${baseUrl}/audio/transcriptions`,
       dictationStreamEndpoint: `${socketBase.href}/audio/transcriptions/stream`,

package/src/server/management/config-routes.ts

@@ -8,6 +8,7 @@ import { catalogModelSlug, invalidateCodexModelsCache, nativeContextLimits, nati
 import {
   applyCodexConfigInjection,
   describeCodexDesktopSwitches,
+  observedCodexDesktopSwitchApply,
   type CodexDesktopSwitchApply,
 } from "../../codex/desktop-switches";
 import {
@@ -360,11 +361,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       codexDesktopAuthless: config.codexDesktopAuthless === true,
       // Absent keeps Design B remote compaction; true selects the dedicated provider identity.
       codexClientCompaction: config.codexClientCompaction === true,
-      codexDesktopSwitches: describeCodexDesktopSwitches(config, {
-        applied: false,
-        reason: "not_requested",
-        retryable: false,
-      }),
+      codexDesktopSwitches: describeCodexDesktopSwitches(config, await observedCodexDesktopSwitchApply()),
       compactionRouting: config.compactionRouting ?? null,
       startupHealth: await readStartupHealth(config),
       codexRuntime: {
@@ -687,7 +684,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     // lock C — awaiting N while still holding C would invert that order.
     const desktopSwitchApply: CodexDesktopSwitchApply = desktopSwitchesChanged
       ? await applyCodexConfigInjection(config)
-      : { applied: false, reason: "not_requested", retryable: false };
+      : await observedCodexDesktopSwitchApply();
     const codexDesktopSwitches = describeCodexDesktopSwitches(config, desktopSwitchApply);
     const catalogRefreshPending = catalogRefresh
       ? catalogRefreshIsPending(catalogRefresh)

package/src/server/management/context.ts

@@ -25,6 +25,11 @@ import type { RequestMetricsSnapshotter } from "../request-metrics";
 
 import type { RemoteWorkspaceHub } from "../../remote-control/workspace-hub";
 import type { RemoteWorkspaceSessionService } from "../../remote-control/workspace-sessions";
+import type { LinkSupervisor } from "../../link/supervisor";
+import type { LinkListenerLifecycle } from "../index/link-listener";
+import type { SshRunner } from "../../link/ssh-runner";
+import type { LinkStore } from "../../link/store";
+import type { IssuedApiKey } from "./oauth-account-routes";
 
 export type RemoteWorkspaceHubApi = Pick<RemoteWorkspaceHub,
   "identity" | "createPairingGrant" | "assertPairingSourceAllowed" | "pairDevice"
@@ -33,6 +38,11 @@ export type RemoteWorkspaceHubApi = Pick<RemoteWorkspaceHub,
 export type RemoteWorkspaceSessionsApi = Pick<RemoteWorkspaceSessionService,
   "availability" | "list" | "create" | "prompt" | "submitPrompt" | "stop" | "shutdown">;
 
+export interface ManagementRequestIngress {
+  trustedLoopback: boolean;
+  guiSessionIssuance?: import("../gui-session").GuiSessionIssuance | null;
+}
+
 export interface ManagementApiDeps {
   /** Read-only process-local aggregate metrics; absent keeps the scrape route unavailable. */
   requestMetrics?: RequestMetricsSnapshotter;
@@ -130,6 +140,17 @@ export interface ManagementApiDeps {
    * `saveConfigPreservingClaudeCode` above exists to prevent.
    */
   codexPromptPaths?: CodexPromptPaths;
+  /** Link seams are getters so the optional listener and supervisor are singletons. */
+  linkSupervisor?: () => LinkSupervisor;
+  linkListener?: () => Pick<LinkListenerLifecycle<unknown>, "ensureStarted" | "status" | "close" | "onAuthenticatedCatalog">;
+  readLinkStore?: () => LinkStore;
+  writeLinkStore?: (store: LinkStore) => void;
+  linkKnownHostsPath?: () => string;
+  sshRunner?: SshRunner;
+  issueApiKey?: (config: OcxConfig, name: string) => IssuedApiKey;
+  revokeApiKey?: (config: OcxConfig, id: string) => boolean;
+  loadLinkCandidates?: () => Array<{ alias: string; source: "ssh_config" | "tailscale" }>;
+  now?: () => number;
 }
 
 
@@ -151,6 +172,10 @@ export interface ManagementContext {
   principal?: ManagementPrincipal;
   /** Narrow current-session revocation seam; contains neither the token nor session map. */
   sessionControl?: ManagementSessionControl;
+  /** Whether the request arrived through a trusted loopback ingress. */
+  trustedLoopbackIngress: boolean;
+  /** The issuance mode of the session, when the principal is a GUI session. */
+  guiSessionIssuance: import("../gui-session").GuiSessionIssuance | null;
   convergeCodexCatalog: () => Promise<CatalogDisposition>;
   syncClaudeAgentDefsBestEffort: () => Promise<void>;
 }