@bitkyc08/opencodex 2.84.0 → 2.86.0

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;
+}
+

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

@@ -0,0 +1,191 @@
+/**
+ * GET / PUT /api/advisor/settings — the advisor sidecar's management surface.
+ *
+ * GET answers the RESOLVED settings (defaults applied, sources marked) plus availability, so the
+ * GUI/CLI show real runtime state rather than stored fields. PUT is a strict partial patch:
+ * unknown keys and wrong types are refused, values are validated against the same resolver the
+ * runtime reads, and the patch persists through the locked config writer with the snapshot-
+ * restore discipline used by PATCH /api/protocols/settings — a refused or failed write never
+ * leaves the live config serving a state the file does not hold.
+ */
+import { activateAdvisor } from "../../lib/advisor-activation";
+import { jsonResponse } from "../auth-cors";
+import { readManagementJsonBodyOr } from "./body";
+import type { ManagementContext } from "./context";
+import {
+  ADVISOR_CONTEXT_SHARING_CONSENT_VERSION,
+  ADVISOR_EFFORTS,
+  advisorContextSharingBlocked,
+  advisorRunnable,
+  isCurrentAdvisorContextSharingConsent,
+  isValidAdvisorEffort,
+  isValidAdvisorPolicy,
+  resolveAdvisorSettings,
+  type AdvisorEffort,
+  type AdvisorPolicy,
+} from "../../advisor/settings";
+
+const INVALID_BODY = Symbol("invalid-body");
+
+interface AdvisorPatch {
+  enabled?: boolean;
+  model?: string;
+  effort?: AdvisorEffort;
+  policy?: AdvisorPolicy;
+  timeoutMs?: number;
+  /** "v1" records current consent. null removes it. Enabling does not imply this field. */
+  contextSharingConsent?: typeof ADVISOR_CONTEXT_SHARING_CONSENT_VERSION | null;
+  reset?: boolean;
+}
+
+type ParsedPatch = { ok: true; patch: AdvisorPatch } | { ok: false; code: string; message: string };
+
+const PATCH_KEYS = new Set(["enabled", "model", "effort", "policy", "timeoutMs", "contextSharingConsent", "reset"]);
+
+type Rec = Record<string, unknown>;
+function isRec(value: unknown): value is Rec {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Strict: unknown keys and wrong types are refused; messages name the field, never the value. */
+export function parseAdvisorSettingsPatch(body: unknown): ParsedPatch {
+  if (!isRec(body)) return { ok: false, code: "invalid_body", message: "body must be a JSON object" };
+  if (Object.keys(body).length === 0) return { ok: false, code: "empty_body", message: "body must set at least one of enabled, model, effort, policy, timeoutMs, contextSharingConsent or reset" };
+  for (const key of Object.keys(body)) {
+    if (!PATCH_KEYS.has(key)) return { ok: false, code: "unknown_field", message: "body accepts only enabled, model, effort, policy, timeoutMs, contextSharingConsent and reset" };
+  }
+  const patch: AdvisorPatch = {};
+  if (body.reset !== undefined) {
+    if (body.reset !== true) return { ok: false, code: "invalid_reset", message: "reset must be true when present" };
+    if (Object.keys(body).length > 1) return { ok: false, code: "reset_with_fields", message: "reset must be the only field when present" };
+    patch.reset = true;
+    return { ok: true, patch };
+  }
+  if (body.enabled !== undefined) {
+    if (typeof body.enabled !== "boolean") return { ok: false, code: "invalid_enabled", message: "enabled must be a boolean" };
+    patch.enabled = body.enabled;
+  }
+  if (body.model !== undefined) {
+    // An empty or whitespace-only value is the supported "clear the model" state, not an error:
+    // the resolver defaults to an empty model and `advisorRunnable` requires a non-blank one. The
+    // only structural rules are the string type and the trimmed length bound.
+    if (typeof body.model !== "string" || body.model.trim().length > 200) {
+      return {
+        ok: false,
+        code: "invalid_model",
+        message: "model must be a string whose trimmed value is at most 200 characters; an empty value clears the advisor model",
+      };
+    }
+    patch.model = body.model.trim();
+  }
+  if (body.effort !== undefined) {
+    if (!isValidAdvisorEffort(body.effort)) {
+      return { ok: false, code: "invalid_effort", message: `effort must be one of ${ADVISOR_EFFORTS.join(", ")}` };
+    }
+    patch.effort = body.effort;
+  }
+  if (body.policy !== undefined) {
+    if (!isValidAdvisorPolicy(body.policy)) {
+      return { ok: false, code: "invalid_policy", message: 'policy must be "manual" or "preflight"' };
+    }
+    patch.policy = body.policy;
+  }
+  if (body.timeoutMs !== undefined) {
+    if (typeof body.timeoutMs !== "number" || !Number.isFinite(body.timeoutMs) || body.timeoutMs < 1_000 || body.timeoutMs > 600_000) {
+      return { ok: false, code: "invalid_timeout", message: "timeoutMs must be a number between 1000 and 600000" };
+    }
+    patch.timeoutMs = Math.floor(body.timeoutMs);
+  }
+  if (body.contextSharingConsent !== undefined) {
+    if (body.contextSharingConsent === null) {
+      patch.contextSharingConsent = null;
+    } else if (isCurrentAdvisorContextSharingConsent(body.contextSharingConsent)) {
+      patch.contextSharingConsent = body.contextSharingConsent;
+    } else {
+      return {
+        ok: false,
+        code: "invalid_context_sharing_consent",
+        message: `contextSharingConsent must be "${ADVISOR_CONTEXT_SHARING_CONSENT_VERSION}" or null`,
+      };
+    }
+  }
+  return { ok: true, patch };
+}
+
+function advisorInfo(config: ManagementContext["config"]): Record<string, unknown> {
+  const settings = resolveAdvisorSettings(config);
+  const warning = settings.enabled && settings.model.trim() === ""
+    ? "advisor_enabled_without_model"
+    : advisorContextSharingBlocked(settings)
+      ? "advisor_context_sharing_consent_required"
+      : undefined;
+  return {
+    settings,
+    runnable: advisorRunnable(settings),
+    // Enabled without a model cannot consult. Enabled with a model but without current
+    // consent must not send task context; the warning names that block.
+    ...(warning ? { warning } : {}),
+  };
+}
+
+function applyPatchInMemory(config: ManagementContext["config"], patch: AdvisorPatch): void {
+  if (patch.reset) {
+    delete config.advisor;
+    return;
+  }
+  const current: Rec = isRec(config.advisor) ? { ...config.advisor } : {};
+  if (patch.enabled !== undefined) current.enabled = patch.enabled;
+  if (patch.model !== undefined) current.model = patch.model;
+  if (patch.effort !== undefined) current.effort = patch.effort;
+  if (patch.policy !== undefined) current.policy = patch.policy;
+  if (patch.timeoutMs !== undefined) current.timeoutMs = patch.timeoutMs;
+  if (patch.contextSharingConsent === null) delete current.contextSharingConsent;
+  else if (patch.contextSharingConsent !== undefined) current.contextSharingConsent = patch.contextSharingConsent;
+  config.advisor = current as ManagementContext["config"]["advisor"];
+}
+
+function isConfigLockContention(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  if ((error as { code?: unknown }).code !== "CONFIG_MUTATION_LOCK_UNAVAILABLE") return false;
+  return (error as { cause?: { code?: unknown } }).cause?.code === "SQLITE_BUSY";
+}
+
+export async function handleAdvisorRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { url, req, config } = ctx;
+  if (url.pathname !== "/api/advisor/settings") return null;
+
+  if (req.method === "GET") return jsonResponse(advisorInfo(config), 200, req, config);
+  if (req.method === "PUT") return putAdvisorSettings(ctx);
+  return null;
+}
+
+async function putAdvisorSettings(ctx: ManagementContext): Promise<Response> {
+  const { req, config } = ctx;
+
+  const body = await readManagementJsonBodyOr(req, INVALID_BODY);
+  const parsed = body === INVALID_BODY
+    ? { ok: false as const, code: "invalid_json", message: "body must be valid JSON" }
+    : parseAdvisorSettingsPatch(body);
+  if (!parsed.ok) return jsonResponse({ error: { code: parsed.code, message: parsed.message } }, 400, req, config);
+
+  // Resolve the writer BEFORE touching the live config: a resolution failure must leave the
+  // in-memory config exactly as it was, not rely on the snapshot restore below.
+  // `deps.` first: route tests with an in-memory fixture must never write the real config.
+  const persist = ctx.deps.saveConfigPreservingClaudeCode
+    ?? (await import("../../config")).saveConfigPreservingClaudeCode;
+  const snapshot = isRec(config.advisor) ? { ...config.advisor } : undefined;
+  applyPatchInMemory(config, parsed.patch);
+  try {
+    persist(config);
+  } catch (error) {
+    // Undo in memory too: a live config that serves a state the file does not hold would
+    // mislead every GET until the next restart.
+    if (snapshot === undefined) delete config.advisor;
+    else config.advisor = snapshot as ManagementContext["config"]["advisor"];
+    return isConfigLockContention(error)
+      ? jsonResponse({ error: { code: "config_busy", message: "Another process is saving the configuration. Try again in a moment." } }, 409, req, config)
+      : jsonResponse({ error: { code: "write_failed", message: "The configuration could not be saved." } }, 500, req, config);
+  }
+  activateAdvisor(config);
+  return jsonResponse(advisorInfo(config), 200, req, config);
+}

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

@@ -1397,6 +1397,24 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   }
 
   // Claude Code inbound settings (GUI "Claude ON" toggle + Claude page).
+  if (url.pathname === "/api/claude-code/model-defaults" && (req.method === "GET" || req.method === "POST")) {
+    const { previewClaudeModelDefaults, applyClaudeModelDefaults, ModelDefaultsRecoveryError } = await import("../../claude/model-default-settings");
+    try {
+      if (req.method === "GET") return jsonResponse(previewClaudeModelDefaults(config.claudeCode?.tierModels));
+      let body: unknown;
+      try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+      if (!body || typeof body !== "object" || Array.isArray(body) || Object.keys(body).length !== 1 ||
+          !("fingerprint" in body) || typeof body.fingerprint !== "string" || !/^[a-f0-9]{64}$/.test(body.fingerprint)) {
+        return jsonResponse({ error: "fingerprint is required" }, 400);
+      }
+      return jsonResponse(applyClaudeModelDefaults(config.claudeCode?.tierModels, body.fingerprint));
+    } catch (error) {
+      rethrowManagementBodyTooLarge(error);
+      if (error instanceof ModelDefaultsRecoveryError) return jsonResponse({ error: error.message, code: error.message, backupPath: error.backupPath }, 500);
+      const code = error instanceof Error && error.message === "settings_changed" ? "settings_changed" : "settings_unavailable";
+      return jsonResponse({ error: code, code }, code === "settings_changed" ? 409 : 500);
+    }
+  }
   if (url.pathname === "/api/claude-code" && req.method === "GET") {
     const models = await fetchAllModels(config);
     const { listCatalogNativeSlugs } = await import("../../codex/catalog");
@@ -1513,10 +1531,10 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     });
   }
   if (url.pathname === "/api/claude-code" && req.method === "PUT") {
-    // NOTE: model / tierModels / maxContextTokens / alwaysEnableEffort are
+    // NOTE: model / maxContextTokens / alwaysEnableEffort are
     // CONFIG-ONLY back-compat fields — the GUI no longer offers controls for them
-    // (default model is owned by Claude Code's /model picker; roster agents
-    // supersede tiers; auto-context supersedes the max-context pair; effort rides
+    // (default model is owned by Claude Code's /model picker;
+    // auto-context supersedes the max-context pair; effort rides
     // regardless on 2.1.207). PUT keeps validating them so hand-written configs
     // and older GUIs stay safe; GUI saves omit them and the spread preserves them.
     let parsedBody: unknown;
@@ -1835,7 +1853,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       }
     }
     if (body.tierModels !== undefined) {
-      // CONFIG-ONLY back-compat (GUI pickers removed — roster agents supersede tiers).
+      // Family defaults also serve third-party callers that request native tier aliases.
       if (body.tierModels === null) {
         delete next.tierModels;
       } else if (!isPlainObject(body.tierModels)) {

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

@@ -27,6 +27,10 @@ function response(): Response {
 }
 
 export async function handleCompanionRoutes(ctx: ManagementContext): Promise<Response | null> {
+  if (ctx.url.pathname === "/api/advisor/settings") {
+    const { handleAdvisorRoutes } = await import("./advisor-routes");
+    return handleAdvisorRoutes(ctx);
+  }
   if (ctx.url.pathname === "/api/companion/open-in-browser" && ctx.req.method === "POST") {
     let body: unknown;
     try {

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

@@ -329,8 +329,8 @@ export async function syncEnabledClientIntegrations(
     config,
     port,
   }, unattended
-    ? ["mcode", "pi", "aside", "raycast", "omo", "commandcode", "droid", "opencode", "kilo"]
-    : ["mcode", "pi", "aside", "raycast", "omo", "cline", "commandcode", "droid", "opencode", "kilo"],
+    ? ["mcode", "pi", "aside", "raycast", "omo", "commandcode", "droid", "opencode", "kilo", "qoder"]
+    : ["mcode", "pi", "aside", "raycast", "omo", "cline", "commandcode", "droid", "opencode", "kilo", "qoder"],
   ...unattended ? [{ refreshOnly: true, admit }] as const : []));
 
   return out;

package/src/server/management/context.ts

@@ -45,6 +45,10 @@ export interface ManagementRequestIngress {
 }
 
 export interface ManagementApiDeps {
+  desktopStartupSettings?: import("../../codex/desktop-compatibility/startup-settings").DesktopStartupSettingsService;
+  desktopCertificateService?: import("../../codex/desktop-compatibility/certificate-service").DesktopCertificateService;
+  desktopCompatibilityRuntime?: import("../../codex/desktop-compatibility/runtime").DesktopCompatibilityRuntime;
+  onDesktopCompatibilityShutdown?: (shutdown: () => Promise<void>) => void;
   /** Bound to this server's lifecycle owner; absent in direct route tests. */
   listLowQuotaEvents?: (limit?: number) => LowQuotaEvent[];
   /** Bound Claude intercept state, injectable for isolated management-route tests. */

package/src/server/management/desktop-compatibility-routes.ts

@@ -0,0 +1,46 @@
+import { jsonResponse } from "../auth-cors";
+import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import type { ManagementContext } from "./context";
+import type { DesktopCertificateService } from "../../codex/desktop-compatibility/certificate-service";
+
+const PATH = "/api/codex/desktop-compatibility/certificate";
+let service: DesktopCertificateService | undefined;
+
+export async function handleDesktopCompatibilityRoutes(ctx: ManagementContext): Promise<Response | null> {
+  if (ctx.url.pathname !== PATH) return null;
+  if (ctx.req.method !== "GET" && ctx.req.method !== "POST") return jsonResponse({ error: "method_not_allowed" }, 405);
+  // A local dashboard confirmation precedes any persisted key or CurrentUser Root mutation.
+  // This is caller provenance, not protection against an arbitrary same-user process.
+  if (ctx.req.method === "POST" && (ctx.principal !== "gui-session" || !ctx.trustedLoopbackIngress)) {
+    return jsonResponse({ error: "local_dashboard_confirmation_required" }, 403);
+  }
+  let action: "prepare" | "trust" | "remove-trust" | "renew" | undefined, fingerprint: string | undefined;
+  if (ctx.req.method === "POST") {
+    let body: unknown;
+    try { body = await readManagementJsonBody(ctx.req); }
+    catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid_json" }, 400); }
+    if (!body || typeof body !== "object" || Array.isArray(body)) return jsonResponse({ error: "invalid_request" }, 400);
+    const value = body as Record<string, unknown>;
+    if (Object.keys(value).some(key => !["action", "fingerprint", "confirmed"].includes(key)) || value.confirmed !== true
+      || typeof value.action !== "string" || !["prepare", "trust", "remove-trust", "renew"].includes(value.action)) return jsonResponse({ error: "invalid_request" }, 400);
+    action = value.action as typeof action;
+    if (action !== "prepare" && (typeof value.fingerprint !== "string" || !/^[A-F0-9]{64}$/.test(value.fingerprint))) {
+      return jsonResponse({ error: "certificate_fingerprint_required" }, 400);
+    }
+    if (action === "prepare" && value.fingerprint !== undefined) return jsonResponse({ error: "unexpected_fingerprint" }, 400);
+    fingerprint = value.fingerprint as string | undefined;
+  }
+  const controller = ctx.deps.desktopCertificateService ?? (service ??= (await import("../../codex/desktop-compatibility/certificate-service")).createDesktopCertificateService());
+  try {
+    const status = action === "prepare" ? await controller.prepare()
+      : action === "trust" ? await controller.trust(fingerprint!)
+      : action === "renew" ? await controller.renew(fingerprint!)
+      : action === "remove-trust" ? await controller.removeTrust(fingerprint!) : await controller.status();
+    return jsonResponse({ ok: true, certificate: status });
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "operation_failed";
+    const allowed = new Set(["unsupported", "busy", "not_prepared", "fingerprint_changed", "app_running", "runtime_running", "app_state_unknown", "trust_unknown", "trust_not_applied",
+      "unsafe_path", "unreadable", "expired", "renewal_required", "protection_failed"]);
+    return jsonResponse({ ok: false, error: allowed.has(code) ? code : "operation_failed" }, 409);
+  }
+}

package/src/server/management/desktop-compatibility-runtime-routes.ts

@@ -0,0 +1,46 @@
+import { jsonResponse } from "../auth-cors";
+import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import type { ManagementContext } from "./context";
+import type { DesktopCompatibilityRuntime } from "../../codex/desktop-compatibility/runtime";
+
+const PATH = "/api/codex/desktop-compatibility/runtime";
+const ERROR_CODES = new Set(["busy", "unsupported", "test_environment", "stopping", "build_unverified", "egress_proxy_invalid",
+  "trust_required", "certificate_expiring", "certificate_not_prepared", "certificate_invalid", "certificate_expired",
+  "native_identity_unverified", "native_routing_unverified", "cleanup_incomplete", "not_running", "connection_invalid", "connection_changed", "connection_cleanup_required", "connection_unavailable"]);
+
+export async function handleDesktopCompatibilityRuntimeRoutes(ctx: ManagementContext): Promise<Response | null> {
+  if (ctx.url.pathname !== PATH) return null;
+  if (ctx.req.method !== "GET" && ctx.req.method !== "POST") return jsonResponse({ error: "method_not_allowed" }, 405);
+  if (ctx.req.method === "POST" && (ctx.principal !== "gui-session" || !ctx.trustedLoopbackIngress)) return jsonResponse({ error: "local_dashboard_confirmation_required" }, 403);
+  let action: "start" | "stop" | "observe" | "apply" | "launch" | undefined;
+  if (ctx.req.method === "POST") {
+    let body: unknown;
+    try { body = await readManagementJsonBody(ctx.req); }
+    catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid_json" }, 400); }
+    if (!body || typeof body !== "object" || Array.isArray(body)) return jsonResponse({ error: "invalid_request" }, 400);
+    const value = body as Record<string, unknown>;
+    if (Object.keys(value).some(key => !["action", "confirmed", "accountWideConsent"].includes(key)) || value.confirmed !== true
+      || typeof value.action !== "string" || !["start", "stop", "observe", "apply", "launch"].includes(value.action)) return jsonResponse({ error: "invalid_request" }, 400);
+    if (value.action === "apply" ? value.accountWideConsent !== true : value.accountWideConsent !== undefined) return jsonResponse({ error: "invalid_consent_scope" }, 400);
+    action = value.action as typeof action;
+  }
+  const module = ctx.deps.desktopCompatibilityRuntime ? null : await import("../../codex/desktop-compatibility/service");
+  const service: DesktopCompatibilityRuntime = ctx.deps.desktopCompatibilityRuntime ?? module!.getDesktopCompatibilityRuntime();
+  if (module) ctx.deps.onDesktopCompatibilityShutdown?.(module.shutdownDesktopCompatibility);
+  try {
+    if (action === "apply") {
+      const result = await service.apply(true);
+      return jsonResponse({ ok: result.accepted, activation: result, runtime: service.status() }, result.accepted ? 202 : 409);
+    }
+    if (action === "launch") {
+      const result = await service.launch();
+      return jsonResponse({ ok: result.status === "started", launch: result, runtime: service.status() }, result.status === "started" ? 200 : 409);
+    }
+    const result = action === "start" ? await service.start() : action === "stop" ? await service.stop()
+      : action === "observe" ? await service.observe() : service.status();
+    return jsonResponse({ ok: true, runtime: result });
+  } catch (error) {
+    const code = error instanceof Error ? error.message.replace(/^desktop_compatibility_/, "") : "operation_failed";
+    return jsonResponse({ ok: false, error: ERROR_CODES.has(code) ? code : "operation_failed", runtime: service.status() }, 409);
+  }
+}

package/src/server/management/desktop-compatibility-settings-routes.ts

@@ -0,0 +1,27 @@
+import { jsonResponse } from "../auth-cors";
+import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import type { ManagementContext } from "./context";
+
+const PATH = "/api/codex/desktop-compatibility/settings";
+export async function handleDesktopCompatibilitySettingsRoutes(ctx: ManagementContext): Promise<Response | null> {
+  if (ctx.url.pathname !== PATH) return null;
+  if (ctx.req.method !== "GET" && ctx.req.method !== "POST") return jsonResponse({ error: "method_not_allowed" }, 405);
+  if (ctx.req.method === "POST" && (ctx.principal !== "gui-session" || !ctx.trustedLoopbackIngress)) return jsonResponse({ error: "local_dashboard_confirmation_required" }, 403);
+  let update: { startOnProxyStart: boolean; revision: string } | undefined;
+  if (ctx.req.method === "POST") {
+    let body: unknown;
+    try { body = await readManagementJsonBody(ctx.req); }
+    catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid_json" }, 400); }
+    if (!body || typeof body !== "object" || Array.isArray(body)) return jsonResponse({ error: "invalid_request" }, 400);
+    const value = body as Record<string, unknown>;
+    if (Object.keys(value).some(key => !["startOnProxyStart", "revision", "confirmed"].includes(key)) || value.confirmed !== true
+      || typeof value.startOnProxyStart !== "boolean" || typeof value.revision !== "string" || !/^[a-f0-9]{64}$/.test(value.revision)) return jsonResponse({ error: "invalid_request" }, 400);
+    update = { startOnProxyStart: value.startOnProxyStart, revision: value.revision };
+  }
+  const service = ctx.deps.desktopStartupSettings ?? (await import("../../codex/desktop-compatibility/startup-settings")).createDesktopStartupSettings({ liveConfig: ctx.config });
+  try { return jsonResponse({ ok: true, settings: update ? service.set(update.startOnProxyStart, update.revision) : service.status() }); }
+  catch (error) {
+    const code = error instanceof Error ? error.message.replace(/^desktop_compatibility_settings_/, "") : "operation_unconfirmed";
+    return jsonResponse({ ok: false, error: ["unavailable", "invalid", "changed", "invalid_request"].includes(code) ? `settings_${code}` : "settings_operation_unconfirmed" }, 409);
+  }
+}

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

@@ -556,9 +556,9 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
       if (!(error instanceof ClientPathError)) throw error;
       return jsonResponse({ error: error.message }, 400, req, config);
     }
-    if ((requested === "raycast" || requested === "droid") && shouldInjectApiAuthHeader(config)) {
+    if ((requested === "raycast" || requested === "droid" || requested === "qoder") && shouldInjectApiAuthHeader(config)) {
       return jsonResponse({
-        error: `${requested === "droid" ? "Factory Droid" : "Raycast"} export requires an unauthenticated loopback destination; this listener requires an admission header the client cannot supply.`,
+        error: `${requested === "droid" ? "Factory Droid" : requested === "qoder" ? "Qoder" : "Raycast"} export requires an unauthenticated loopback destination; this listener requires an admission header the client cannot supply.`,
         reason: "non_loopback",
       }, 400, req, config);
     }

package/src/server/management/protocol-settings-patch.ts

@@ -31,6 +31,7 @@ export const PROTOCOL_ROLLOUT_KEYS = [
   "managedMessagesNative",
   "managedMessagesNativeOAuth",
   "directEncoders",
+  "antigravityDirect",
   "shadowPlan",
 ] as const satisfies readonly (keyof ProtocolRolloutSettings)[];
 const ROLLOUT_KEYS = new Set<string>(PROTOCOL_ROLLOUT_KEYS);

package/src/server/management/route-registry.ts

@@ -139,6 +139,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "POST", path: "/api/native-main-profiles/switch", module: "codex/native-profile-api", mutates: true },
   // server/management/agent-settings-routes
   { method: "GET", path: "/api/claude-code", module: "server/management/agent-settings-routes", mutates: false },
+  { method: "GET", path: "/api/claude-code/model-defaults", module: "server/management/agent-settings-routes", mutates: false, exempt: { reason: "interactive-preview", why: "Preview half of the GUI-only Claude Code tier-default apply; the fingerprint it returns is the only input POST accepts, and no terminal confirmation workflow exists yet." } },
+  { method: "POST", path: "/api/claude-code/model-defaults", module: "server/management/agent-settings-routes", mutates: true, exempt: { reason: "interactive-preview", why: "Apply half of the GUI-only Claude Code tier-default preview; it writes the shared Claude settings only for a fingerprint the dashboard preview produced." } },
   { method: "GET", path: "/api/claude-desktop", module: "server/management/agent-settings-routes", mutates: false },
   { method: "GET", path: "/api/claude-desktop/status", module: "server/management/agent-settings-routes", mutates: false },
   { method: "GET", path: "/api/codex-auth/features/default-mode-request-user-input", module: "server/management/agent-settings-routes", mutates: false },
@@ -163,6 +165,12 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   // server/management/claude-desktop-picker-routes
   { method: "GET", path: "/api/claude-desktop/picker", module: "server/management/claude-desktop-picker-routes", mutates: false },
   { method: "PUT", path: "/api/claude-desktop/picker", module: "server/management/claude-desktop-picker-routes", mutates: true },
+  { method: "GET", path: "/api/codex/desktop-compatibility/certificate", module: "server/management/desktop-compatibility-routes", mutates: false, mechanism: "path-constant", exempt: { reason: "deferred-verb", owner: "codex-desktop-compatibility", ownerDoc: "structure/clients/codex-desktop.md", why: "Certificate status is available over authenticated HTTP while the desktop compatibility runtime/CLI status contract is integrated." } },
+  { method: "POST", path: "/api/codex/desktop-compatibility/certificate", module: "server/management/desktop-compatibility-routes", mutates: true, mechanism: "path-constant", exempt: { reason: "session-only", why: "Certificate setup requires a confirmed local dashboard session; raw admin tokens cannot enroll or remove OS trust." } },
+  { method: "GET", path: "/api/codex/desktop-compatibility/runtime", module: "server/management/desktop-compatibility-runtime-routes", mutates: false, mechanism: "path-constant", exempt: { reason: "deferred-verb", owner: "codex-desktop-compatibility", ownerDoc: "structure/clients/codex-desktop.md", why: "Experimental runtime status is authenticated HTTP while the native compatibility UI and CLI contract are integrated." } },
+  { method: "POST", path: "/api/codex/desktop-compatibility/runtime", module: "server/management/desktop-compatibility-runtime-routes", mutates: true, mechanism: "path-constant", exempt: { reason: "session-only", why: "Native app launch and account-wide UI trial require explicit local dashboard confirmation." } },
+  { method: "GET", path: "/api/codex/desktop-compatibility/settings", module: "server/management/desktop-compatibility-settings-routes", mutates: false, mechanism: "path-constant", exempt: { reason: "deferred-verb", owner: "codex-desktop-compatibility", ownerDoc: "structure/clients/codex-desktop.md", why: "The persisted startup preference is currently owned by the local desktop compatibility panel." } },
+  { method: "POST", path: "/api/codex/desktop-compatibility/settings", module: "server/management/desktop-compatibility-settings-routes", mutates: true, mechanism: "path-constant", exempt: { reason: "session-only", why: "Saved native observation intent requires an explicit local GUI action and fresh field revision." } },
   { method: "PUT", path: "/api/codex-auth/features/default-mode-request-user-input", module: "server/management/agent-settings-routes", mutates: true },
   { method: "PUT", path: "/api/effort-caps", module: "server/management/agent-settings-routes", mutates: true },
   { method: "PUT", path: "/api/grok/selection", module: "server/management/agent-settings-routes", mutates: true },
@@ -267,6 +275,9 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/usage", module: "server/management/logs-usage-routes", mutates: false },
   // server/management/usage-timeline-routes
   { method: "GET", path: "/api/usage/timeline", module: "server/management/usage-timeline-routes", mutates: false },
+  // server/management/advisor-routes
+  { method: "GET", path: "/api/advisor/settings", module: "server/management/advisor-routes", mutates: false },
+  { method: "PUT", path: "/api/advisor/settings", module: "server/management/advisor-routes", mutates: true },
   // server/management/companion-routes
   { method: "POST", path: "/api/companion/open-in-browser", module: "server/management/companion-routes", mutates: true, exempt: { reason: "browser-navigation", why: "Opens the companion's current view in the system browser under normal management admission; the CLI reads the underlying settings and usage directly." } },
   { method: "GET", path: "/api/companion/settings", module: "server/management/companion-routes", mutates: false },