@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

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

@@ -205,7 +205,7 @@ export function setGrokApplyFlightTestHooks(
   grokApplyFlight = null;
   grokApplyHighWaterBytes = 0;
 }
-import type { ManagementContext } from "./context";
+import { managementInferencePort, type ManagementContext } from "./context";
 
 async function injectionModelOptions(config: OcxConfig, models: readonly CatalogModel[]) {
   const disabled = new Set(config.disabledModels ?? []);
@@ -262,7 +262,8 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         const writtenProfile = current.claudeCode.desktopProfile;
         const markerBaseline = captureDesktopAppliedMarker(writtenProfile);
         const result = (deps.writeDesktop3pConfig ?? writeDesktop3pConfig)(
-          current.port ?? 10100,
+          // Live bound port, not config: a CLI override or ephemeral bind must not strand Desktop (#6598).
+          managementInferencePort({ config: current, deps }) ?? 10100,
           [...desktopVisibleNativeSlugs(current)],
           routed,
           current.apiKeys?.[0]?.key,
@@ -761,135 +762,9 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     });
   }
 
-  // Featured roster and saved picker order are separate settings. Native Codex advertises
-  // the first five eligible visible rows by display priority; OCX guidance uses natural ranks.
-  if (url.pathname === "/api/subagent-models" && req.method === "GET") {
-    const models = await (deps.fetchAllModels ?? fetchAllModels)(config);
-    // Native gpt (passthrough) are also valid subagent picks — they're picker-visible models in the
-    // catalog, just buried by priority. List them first so the user can feature them over routed.
-    const [{ listCatalogNativeSlugs }, { subagentSelectableModels }] = await Promise.all([
-      import("../../codex/catalog"),
-      import("../../codex/subagent-selectable-models"),
-    ]);
-    const chosen = config.subagentModels ?? [];
-    // A saved roster slot must stay representable even after its model is disabled
-    // elsewhere (Models page, provider allowlist, a provider row going away). The
-    // dashboard treats `available` as the set of rows it can render, so a chosen id
-    // missing from it disappears from the roster UI and the next Save — which PUTs
-    // exactly what the UI holds — silently truncates the persisted list. Losing a
-    // deliberate 5-model roster to an unrelated visibility toggle is data loss, not a
-    // filter. Same reasoning as `fetchGrokCandidateModels`, which deliberately lists a
-    // model the user already excluded so its switch remains reachable.
-    const available = subagentSelectableModels(config, models, listCatalogNativeSlugs());
-    // #857: let CLI/GUI show when a running Codex app-server keeps an older
-    // in-memory catalog than the one on disk. Bounded request-path read: the synchronous
-    // collector blocked the event loop for the whole Windows CIM walk (4-7s measured).
-    const {
-      collectCodexAppServerCatalogStateWithin,
-      DASHBOARD_CATALOG_STATE_DEADLINE_MS,
-    } = await import("../../codex/app-server-processes");
-    const catalogState = await collectCodexAppServerCatalogStateWithin(DASHBOARD_CATALOG_STATE_DEADLINE_MS);
-    return jsonResponse({
-      chosen, available, catalogState,
-      pickerAvailable: [...new Set(filterCatalogVisibleModels(models, config).map(catalogModelSlug).filter(slug => slug.includes("/")))],
-      pickerOrder: config.modelPickerOrder ?? [],
-      pickerOrderMode: config.modelPickerOrderMode ?? null,
-    });
-  }
-  if (url.pathname === "/api/subagent-models" && req.method === "PUT") {
-    let rawBody: unknown;
-    try { rawBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
-    if (!isPlainRecord(rawBody)) return jsonResponse({ error: "JSON body must be an object" }, 400);
-    const body = rawBody as { models?: unknown; pickerOrder?: unknown; pickerOrderMode?: unknown };
-    const updatesRoster = body.models !== undefined;
-    const updatesPicker = body.pickerOrder !== undefined;
-    if (!updatesRoster && !updatesPicker) return jsonResponse({ error: "models or pickerOrder is required" }, 400);
-    let chosen: string[] | undefined;
-    if (updatesRoster) {
-      if (!Array.isArray(body.models) || body.models.some(model => typeof model !== "string")) {
-        return jsonResponse({ error: "models must be an array of strings" }, 400);
-      }
-      // Keep the original valid roster contract: no discovery validation, trimming or deduping.
-      chosen = body.models.slice(0, 5);
-    }
-    const mode = body.pickerOrderMode;
-    if (mode !== undefined && (!updatesPicker || (mode !== null
-      && mode !== "alphabetical" && mode !== "provider" && mode !== "most-used"))) {
-      return jsonResponse({ error: "pickerOrderMode requires pickerOrder and must be alphabetical, provider, most-used, or null" }, 400);
-    }
-    let pickerOrder: string[] | undefined;
-    if (updatesPicker) {
-      if (body.pickerOrder !== null && (!Array.isArray(body.pickerOrder)
-        || body.pickerOrder.some(model => typeof model !== "string" || model.trim() === ""))) {
-        return jsonResponse({ error: "pickerOrder must be an array of non-empty routed model ids, or null" }, 400);
-      }
-      pickerOrder = body.pickerOrder === null ? [] : (body.pickerOrder as string[]).map(model => model.trim());
-      if (new Set(pickerOrder).size !== pickerOrder.length) {
-        return jsonResponse({ error: "pickerOrder must not contain duplicate ids" }, 400);
-      }
-      if (pickerOrder.length > 0) {
-        const models = await (deps.fetchAllModels ?? fetchAllModels)(config);
-        // Evaluate visibility AFTER discovery: a concurrent visibility write may have completed.
-        const visible = new Set(filterCatalogVisibleModels(models, config).map(catalogModelSlug).filter(slug => slug.includes("/")));
-        // A bare native id orders the complete picker (docs: guides/model-ordering.md).
-        for (const row of nativeModelRows(config)) if (!row.disabled) visible.add(row.slug);
-        if (pickerOrder.some(model => !visible.has(model))) {
-          return jsonResponse({ error: "pickerOrder must contain visible routed or native model ids, each at most once" }, 400);
-        }
-      }
-    }
-
-    // Everything above can await. From this snapshot through persistence there is no yield.
-    // Stage deletion intent before adopting the touched fields through the canonical
-    // live deletion owner. A failed save restores both fields and pending intent.
-    if (updatesPicker && config.configRebaseProvenance !== undefined
-      && parsedConfigRebaseDeletionKeys(config) === null) {
-      // A newer provenance format must not silently discard this clear's intent on rebase.
-      return jsonResponse({ error: "unsupported config deletion provenance" }, 409);
-    }
-    const draft = { ...projectConfigRebaseProvenance(config) };
-    if (chosen !== undefined) draft.subagentModels = chosen;
-    if (pickerOrder !== undefined) {
-      if (pickerOrder.length === 0) {
-        deleteConfigTopLevelKey(draft, "modelPickerOrder");
-        deleteConfigTopLevelKey(draft, "modelPickerOrderMode");
-      } else {
-        draft.modelPickerOrder = pickerOrder;
-        if (mode === "alphabetical" || mode === "provider" || mode === "most-used") draft.modelPickerOrderMode = mode;
-        else deleteConfigTopLevelKey(draft, "modelPickerOrderMode");
-      }
-    }
-    const projected = projectConfigRebaseProvenance(draft);
-    const touched = [
-      ...(updatesRoster ? ["subagentModels" as const] : []),
-      ...(updatesPicker ? ["modelPickerOrder" as const, "modelPickerOrderMode" as const] : []),
-      "configRebaseProvenance" as const,
-    ];
-    const rollback = captureConfigTopLevelRollback(config, touched);
-    try {
-      for (const key of touched) {
-        if (Object.hasOwn(projected, key)) Object.defineProperty(config, key, {
-          value: projected[key], writable: true, enumerable: true, configurable: true,
-        });
-        else deleteConfigTopLevelKey(config, key);
-      }
-      (deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode)(config);
-    } catch (error) {
-      rollback();
-      throw error;
-    }
-    // Capture the result before convergence yields to another settings mutation.
-    const saved = {
-      applied: [...(config.subagentModels ?? [])],
-      pickerOrder: [...(config.modelPickerOrder ?? [])],
-      pickerOrderMode: config.modelPickerOrderMode ?? null,
-    };
-    const catalogRefresh = await convergeCodexCatalog();
-    if (updatesRoster) {
-      await syncClaudeAgentDefsBestEffort();
-      await autoApplyDesktopBestEffort();
-    }
-    return jsonResponse({ ok: true, ...saved, catalogRefresh });
+  if (url.pathname === "/api/subagent-models") {
+    const { handleSubagentModelRoutes } = await import("./subagent-model-routes");
+    return handleSubagentModelRoutes(ctx, autoApplyDesktopBestEffort);
   }
 
   // Priority-ordered subagent model fallback chain for quota-aware spawn routing.
@@ -1024,7 +899,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   if (url.pathname === "/api/claude-desktop" && req.method === "GET") {
     try {
       const state = await buildClaudeDesktopState(config);
-      const runtimePort = Number(url.port) || config.port;
+      const runtimePort = managementInferencePort(ctx);
       return jsonResponse({ ...state, port: runtimePort });
     } catch (error) {
       return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
@@ -1092,7 +967,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         };
       }
       const saved = await buildClaudeDesktopState(config);
-      const runtimePort = Number(url.port) || config.port;
+      const runtimePort = managementInferencePort(ctx);
       return jsonResponse({ ok: true, ...saved, port: runtimePort });
     } catch (error) {
       return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
@@ -1194,6 +1069,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
           const picker = modeSaved.ok && pickerPreferenceOn(loadConfig())
             ? await ops.enableLocked({ persist: false, context: "server" })
             : await pickerStatusFor(loadConfig());
+          if (modeSaved.ok) await syncClaudeAgentDefsBestEffort();
           return jsonResponse({
             ok: true,
             mode: "first-party",
@@ -1256,7 +1132,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         // Picker mode belongs to first-party: stop terminating claude.ai before the gateway lands.
         const pickerOff = await ops.disableLocked({ persist: false });
         const result = (deps.writeDesktop3pConfig ?? writeDesktop3pConfig)(
-          Number(url.port) || latest.port,
+          managementInferencePort({ config: latest, deps }),
           [...desktopVisibleNativeSlugs(latest)],
           routed,
           latest.apiKeys?.[0]?.key,
@@ -1542,6 +1418,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         ? { visionSidecar: { backend: visionOverride.backend, model: visionOverride.model } }
         : {}),
       fastMode: config.fastMode,
+      forceAvailable: [...visibleNativeSlugs(config), ...filterCatalogVisibleModels(models, config).map(catalogModelSlug)],
       contextWindows,
       effectiveModelEnv: effectiveModelEnv(config.claudeCode, contextWindows),
       available,
@@ -1678,6 +1555,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       const finalDesired = firstPartyDesired(config, observeClaudeDesktopMode(config));
       const residual = !finalDesired.desktop && !finalDesired.cli
         && readFirstPartyProxyStatus(config, bound?.proxyPort ?? null) !== "none";
+      await syncClaudeAgentDefsBestEffort();
       return jsonResponse({ ok: true, enabled: config.claudeCode?.enabled !== false,
         cliFirstParty: body.cliFirstParty,
         warnings: [

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

@@ -276,7 +276,7 @@ export async function syncEnabledClientIntegrations(
     },
     config,
     port,
-  }, ["mcode", "pi", "aside", "raycast", "omo", "cline", "droid"]));
+  }, ["mcode", "pi", "aside", "raycast", "omo", "cline", "droid", "opencode", "kilo"]));
 
   return out;
 }

package/src/server/management/context.ts

@@ -160,7 +160,7 @@ export interface ManagementApiDeps {
   issueApiKey?: (config: OcxConfig, name: string) => IssuedApiKey;
   revokeApiKey?: (config: OcxConfig, id: string) => boolean;
   loadLinkCandidates?: () => Array<{ alias: string; source: "ssh_config" | "tailscale" }>;
-  /** The port this runtime listens on; a join is refused unless it is the configured port. */
+  /** Bound public inference port, not the ingress receiving this management request. */
   liveListenPort?: () => number | undefined;
   now?: () => number;
 }
@@ -191,3 +191,10 @@ export interface ManagementContext {
   convergeCodexCatalog: () => Promise<CatalogDisposition>;
   syncClaudeAgentDefsBestEffort: () => Promise<void>;
 }
+
+/** A management-only ingress cannot supply the port used by generated inference clients. */
+export function managementInferencePort(ctx: Pick<ManagementContext, "config" | "deps">): number {
+  // Lifecycle owns the actual port (including CLI overrides/ephemeral binds); direct route
+  // fixtures fall back to config without consulting another runtime's state file.
+  return ctx.deps.liveListenPort?.() ?? ctx.config.port;
+}

package/src/server/management/cursor-integration-routes.ts

@@ -53,9 +53,9 @@ export async function buildCursorIntegrationStatus(
   const privateInference = pick(installs, "private-inference");
   const regular = pick(installs, "regular");
   const runtime = (deps.readRuntimePort ?? readRuntimePort)(process.pid);
-  // The port the browser reached is the one Cursor on the same machine will reach too; the
-  // runtime record and config.port are fallbacks for a request that carries no port.
-  const port = runtime?.port ?? (Number(ctx.url?.port) || config.port);
+  // The lifecycle-bound public port wins, then the PID-matched runtime record, then config.
+  // A management-only ingress port must never become the Cursor gateway (#6598).
+  const port = deps.liveListenPort?.() ?? runtime?.port ?? config.port;
   // Cursor runs on this machine, so the gateway URL it is told to paste is the LOCAL one: the
   // unauthenticated loopback listener when one is enabled, and otherwise the bind address on the
   // public port — 127.0.0.1 for a loopback or wildcard bind exactly as before, and the tailnet

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

@@ -24,7 +24,8 @@ import {
   type IntegrationClientId,
 } from "../../integrations/registry";
 import { detectRaycast, type RaycastInstall } from "../../integrations/raycast-detect";
-import { readIntegrationState } from "../../integrations/state";
+import { readIntegrationState, readOwnedDroidReasoningDefaults } from "../../integrations/state";
+import { droidReasoningModels, validateDroidReasoningDefaults } from "../../clients/config-export";
 import { createIntegrationStateStore, type IntegrationStateStore } from "../../integrations/store";
 import {
   applyIntegrationCoordinated,
@@ -45,7 +46,7 @@ import {
 } from "../../integrations/mutation-flight";
 import { jsonResponse } from "../auth-cors";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
-import type { ManagementContext } from "./context";
+import { managementInferencePort, type ManagementContext } from "./context";
 import { exportSnapshotIdentity, loadExportModels, previewExportSnapshot } from "./model-rows";
 import {
   previewIntegration,
@@ -74,6 +75,10 @@ export type IntegrationStateEnvelope = {
    * the shared `IntegrationStatus`, which describes the file, not the app.
    */
   raycast?: RaycastInstall;
+  droidReasoning?: {
+    models: Array<{ model: string; label: string; efforts: string[] }>;
+    defaults: Record<string, string>;
+  };
 } & IntegrationStateRecord;
 
 export interface IntegrationStateListEnvelope {
@@ -225,7 +230,7 @@ function asideOptions(ctx: ManagementContext): AsideProfileRouteOptions {
   return {
     input: () => input ??= {
       config: ctx.config,
-      port: Number(ctx.url.port) || ctx.config.port,
+      port: managementInferencePort(ctx),
       models: () => loadExportModels(ctx.config),
       store: integrationStore(),
       ...pathOverrides(),
@@ -241,12 +246,14 @@ async function buildIntegrationWriteInput(
   clientId: IntegrationClientId,
   ctx: ManagementContext,
   store: IntegrationStateStore,
+  droidReasoningDefaults?: Record<string, string>,
 ): Promise<IntegrationWriteInput> {
   return {
     clientId,
     models: await loadExportModels(ctx.config),
     config: ctx.config,
-    port: Number(ctx.url.port) || ctx.config.port,
+    port: managementInferencePort(ctx),
+    ...(droidReasoningDefaults === undefined ? {} : { droidReasoningDefaults: { ...droidReasoningDefaults } }),
     store,
     io: integrationMutationTestHooks?.io,
     ...pathOverrides(),
@@ -265,6 +272,7 @@ async function buildIntegrationPreviewInput(
   clientId: IntegrationClientId,
   ctx: ManagementContext,
   store: IntegrationStateStore,
+  droidReasoningDefaults?: Record<string, string>,
 ): Promise<{ input: IntegrationWriteInput; identity: string } | null> {
   const snapshot = previewExportSnapshot(ctx.config);
   // No cached roster means no honest snapshot to plan against. Gathering one here would make a
@@ -276,7 +284,8 @@ async function buildIntegrationPreviewInput(
       clientId,
       models: snapshot.models,
       config: ctx.config,
-      port: Number(ctx.url.port) || ctx.config.port,
+      port: managementInferencePort(ctx),
+      ...(droidReasoningDefaults === undefined ? {} : { droidReasoningDefaults: { ...droidReasoningDefaults } }),
       store,
       io: integrationMutationTestHooks?.io,
       ...pathOverrides(),
@@ -309,6 +318,31 @@ function invalidClientResponse(ctx: ManagementContext): Response {
   }, 400, ctx.req, ctx.config);
 }
 
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    && Object.values(value).every(item => typeof item === "string");
+}
+
+function invalidDroidDefaultsResponse(ctx: ManagementContext, message: string): Response {
+  return jsonResponse({ error: message, code: "invalid_droid_reasoning_defaults" }, 400, ctx.req, ctx.config);
+}
+
+function readDroidReasoningDefaults(
+  ctx: ManagementContext,
+  body: Record<string, unknown>,
+  clientId: string,
+  operation: IntegrationPlanOperation,
+): Record<string, string> | Response | undefined {
+  if (!Object.hasOwn(body, "droidReasoningDefaults")) return undefined;
+  if (clientId !== "droid" || (operation !== "apply" && operation !== "overwrite")) {
+    return invalidDroidDefaultsResponse(ctx, "droidReasoningDefaults is allowed only for Droid apply or overwrite");
+  }
+  const defaults = body.droidReasoningDefaults;
+  return isStringRecord(defaults)
+    ? defaults
+    : invalidDroidDefaultsResponse(ctx, "droidReasoningDefaults must map model names to effort strings");
+}
+
 /**
  * No cached model roster, so there is nothing honest to plan against.
  *
@@ -364,6 +398,7 @@ function stalePlanGuard(
   request: PreviewRequest,
   fingerprint: string,
   capturedIdentity: string | null,
+  droidReasoningDefaults?: Record<string, string>,
 ): {
   revalidate: NonNullable<CoordinatedIntegrationOptions["revalidate"]>;
   response: () => Response | null;
@@ -379,7 +414,7 @@ function stalePlanGuard(
        * without ever swapping the roster this mutation is about to use.
        */
       if (exportSnapshotIdentity(ctx.config) !== capturedIdentity) {
-        const refreshed = await buildIntegrationPreviewInput(clientId, ctx, store);
+        const refreshed = await buildIntegrationPreviewInput(clientId, ctx, store, droidReasoningDefaults);
         stale = refreshed === null ? "unavailable" : previewIntegration(refreshed.input, request);
         return { ok: false, reason: "conflict", state: "conflict", clientId, message: "the model roster changed while confirming" };
       }
@@ -584,7 +619,7 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
   if (url.pathname === "/api/client-integrations" && req.method === "GET") {
     try {
       const models = await loadExportModels(ctx.config);
-      const port = Number(url.port) || ctx.config.port;
+      const port = managementInferencePort(ctx);
       // One store for the whole collection read: without it this route retried
       // maintenance and counted snapshots in the default store even when the
       // caller had bound everything else to a temp root (A-gate round 13).
@@ -723,9 +758,17 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
         code: "invalid_preview_operation",
       }, 400, req, ctx.config);
     }
+    const droidDefaults = readDroidReasoningDefaults(ctx, parsed, previewClient, operation);
+    if (droidDefaults instanceof Response) return droidDefaults;
     try {
-      const captured = await buildIntegrationPreviewInput(previewClient as IntegrationClientId, ctx, integrationStore());
+      const captured = await buildIntegrationPreviewInput(
+        previewClient as IntegrationClientId, ctx, integrationStore(), droidDefaults,
+      );
       if (!captured) return previewUnavailableResponse(ctx);
+      if (droidDefaults !== undefined) {
+        const invalid = validateDroidReasoningDefaults(captured.input.models, droidDefaults);
+        if (invalid) return invalidDroidDefaultsResponse(ctx, invalid);
+      }
       return jsonResponse(previewIntegration(captured.input, { operation }), 200, req, ctx.config);
     } catch (error) {
       return internalErrorResponse(error, ctx);
@@ -907,7 +950,15 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
       // process spawn, and no other client's read should pay for it.
       const envelope: IntegrationStateEnvelope = requestedClient === "raycast"
         ? { ...state, raycast: (raycastDetectTestHook ?? detectRaycast)() }
-        : state;
+        : requestedClient === "droid"
+          ? {
+              ...state,
+              droidReasoning: {
+                models: droidReasoningModels(input.models),
+                defaults: readOwnedDroidReasoningDefaults(input),
+              },
+            }
+          : state;
       return jsonResponse(envelope, 200, req, ctx.config);
     } catch (error) {
       return internalErrorResponse(error, ctx);
@@ -944,6 +995,8 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
   const requestedOperation: IntegrationPlanOperation = parsed.enabled
     ? (parsed.overwriteConflict === true ? "overwrite" : "apply")
     : "disable";
+  const droidDefaults = readDroidReasoningDefaults(ctx, parsed, requestedClient, requestedOperation);
+  if (droidDefaults instanceof Response) return droidDefaults;
   const binding = planBindingOf(parsed);
   if (binding === "half") return halfBoundResponse(ctx);
   if (binding === "unknown-operation" || (binding !== "none" && binding.operation !== requestedOperation)) {
@@ -964,11 +1017,15 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
      */
     const boundToggle = binding === "none"
       ? null
-      : await buildIntegrationPreviewInput(requestedClient, ctx, integrationStore());
+      : await buildIntegrationPreviewInput(requestedClient, ctx, integrationStore(), droidDefaults);
     if (binding !== "none" && boundToggle === null) return previewUnavailableResponse(ctx);
     const input = boundToggle
       ? boundToggle.input
-      : await buildIntegrationWriteInput(requestedClient, ctx, integrationStore());
+      : await buildIntegrationWriteInput(requestedClient, ctx, integrationStore(), droidDefaults);
+    if (droidDefaults !== undefined) {
+      const invalid = validateDroidReasoningDefaults(input.models, droidDefaults);
+      if (invalid) return invalidDroidDefaultsResponse(ctx, invalid);
+    }
     const guard = binding === "none" ? null : stalePlanGuard(
       requestedClient,
       ctx,
@@ -976,6 +1033,7 @@ export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<R
       { operation: binding.operation },
       binding.fingerprint,
       boundToggle === null ? null : boundToggle.identity,
+      droidDefaults,
     );
     const result = await runIntegrationMutationFlight(
       requestedClient,

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

@@ -86,7 +86,7 @@ function port(value: unknown): value is number {
   return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535;
 }
 
-/** A paired GUI session. Only hub runtimes issue these. */
+/** A GUI session redeemed from an operator-created, one-use pairing grant. */
 function pairedSession(ctx: ManagementContext): boolean {
   return ctx.principal === "gui-session"
     && ctx.sessionControl?.isPaired(ctx.req, ctx.config) === true;
@@ -96,9 +96,8 @@ function pairedSession(ctx: ManagementContext): boolean {
  * A paired session, or on a standalone runtime the current loopback-issued session that reached
  * the public listener bound to a loopback hostname. The loopback bootstrap mints that session
  * without a credential, so this is casual-path protection like POST /api/github/star, not a
- * secret-backed boundary like the admin token. Hubs keep the paired-only rule. Join admits this
- * session too: turning a Child on from its own dashboard is the point of the route, and the
- * dashboard warns first that the restart briefly interrupts running Codex turns.
+ * secret-backed boundary like the admin token. Hubs keep the paired-only rule. Durable operations
+ * that require operator approval, such as joining this machine as a Child, use pairedSession.
  */
 function dashboardSession(ctx: ManagementContext): boolean {
   if (pairedSession(ctx)) return true;
@@ -113,9 +112,10 @@ function adminLoopback(ctx: ManagementContext): boolean {
   return ctx.principal === "admin-token" && ctx.trustedLoopbackIngress;
 }
 
-function auth(ctx: ManagementContext, kind: "dashboard" | "admin" | "either"): Response | null {
+function auth(ctx: ManagementContext, kind: "dashboard" | "paired" | "admin" | "either"): Response | null {
   if (ctx.guiSessionIssuance === "tailscale-identity") return fail("tailscale_session_refused", "Tailscale identity sessions cannot use link routes.", 403);
   const allowed = kind === "dashboard" ? dashboardSession(ctx)
+    : kind === "paired" ? pairedSession(ctx)
     : kind === "admin" ? adminLoopback(ctx)
       : dashboardSession(ctx) || adminLoopback(ctx);
   return allowed ? null : fail("forbidden", "The required link authorization was not present.", 403);
@@ -131,9 +131,14 @@ function joinPortMatches(ctx: ManagementContext): boolean {
   return live !== undefined && live === ctx.config.port;
 }
 
-/** Whether `POST /api/link/join` would pass its admission, role and port gates for this caller. */
-function joinAvailable(ctx: ManagementContext): boolean {
-  return dashboardSession(ctx) && (ctx.config.runtimeRole ?? "standalone") === "standalone" && joinPortMatches(ctx);
+type LinkJoinDenied = "pairing_required" | "standalone_required" | "join_port_mismatch";
+
+/** Read-only explanation of the join gates, in the same order as `POST /api/link/join`. */
+function joinDenied(ctx: ManagementContext): LinkJoinDenied | null {
+  if (!pairedSession(ctx)) return "pairing_required";
+  if ((ctx.config.runtimeRole ?? "standalone") !== "standalone") return "standalone_required";
+  if (!joinPortMatches(ctx)) return "join_port_mismatch";
+  return null;
 }
 
 function runnerFor(ctx: ManagementContext): SshRunner {
@@ -549,9 +554,9 @@ export async function handleLinkRoutes(ctx: ManagementContext, suppliedState?: L
   if (!isLinkPath(path)) return null;
   if (ctx.guiSessionIssuance === "tailscale-identity") return fail("tailscale_session_refused", "Tailscale identity sessions cannot use link routes.", 403);
   if (url.pathname === "/api/link/join" && req.method === "POST") {
-    // The same dashboard admission as the Home side. Every refusal below runs before link state
-    // is read and before any SSH.
-    const denied = auth(ctx, "dashboard");
+    // Joining durably redirects local client traffic, so a credentiallessly bootstrapped loopback
+    // session is insufficient. Every refusal below runs before link state and before any SSH.
+    const denied = auth(ctx, "paired");
     if (denied) return denied;
     if ((ctx.config.runtimeRole ?? "standalone") !== "standalone") return fail("standalone_required", "Client initiated links require standalone runtime mode.", 409);
     if (!joinPortMatches(ctx)) return fail("join_port_mismatch", "OpenCodex is not running on its configured port, so it cannot restart as a Child.", 409);
@@ -578,9 +583,11 @@ export async function handleLinkRoutes(ctx: ManagementContext, suppliedState?: L
       const failure = state.compensationFailures?.get(store.links[0].id);
       if (failure) Object.assign(dto.child, { state: "failed" as const, since: failure.since, reason: failure.reason });
     }
-    // A dashboard session also learns whether it may join as a Child. The admin-token answer stays
+    // A dashboard session also learns why it cannot join as a Child. The admin-token answer stays
     // the exact K16 document that `ocx link status` validates key by key.
-    const body: LinkStatusDto & { joinAvailable?: boolean } = ctx.principal === "gui-session" ? { ...dto, joinAvailable: joinAvailable(ctx) } : dto;
+    const denial = ctx.principal === "gui-session" ? joinDenied(ctx) : null;
+    const body: LinkStatusDto & { joinAvailable?: boolean; joinDenied?: LinkJoinDenied | null } = ctx.principal === "gui-session"
+      ? { ...dto, joinAvailable: denial === null, joinDenied: denial } : dto;
     return Response.json(body, { headers: { "cache-control": "no-store" } });
   }
   if (url.pathname === "/api/link/candidates" && req.method === "GET") {

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

@@ -167,7 +167,7 @@ import type {
 
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels } from "./shared";
 import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
-import type { ManagementContext } from "./context";
+import { managementInferencePort, type ManagementContext } from "./context";
 import { effectiveModelReasoningEfforts, inheritedModelReasoningEfforts, listManagementModelRows, loadExportModels } from "./model-rows";
 import { initialModelSelectionPending } from "../../providers/initial-model-selection";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
@@ -204,7 +204,7 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
       ?? (await import("../../integrations/catalog-refresh")).refreshOwnedCatalogIntegrations;
     const clientIntegrations = await refresh({
       config,
-      port: Number(url.port) || config.port,
+      port: managementInferencePort(ctx),
       models: () => loadExportModels(config),
     });
     return { catalogRefresh, clientIntegrations };
@@ -562,7 +562,7 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
         reason: "non_loopback",
       }, 400, req, config);
     }
-    const baseUrl = opencodeProxyBaseUrl(Number(url.port) || config.port, config.hostname, config);
+    const baseUrl = opencodeProxyBaseUrl(managementInferencePort(ctx), config.hostname, config);
     let models: ExportModel[];
     try {
       // The ONE loader every export surface uses. It carries the visibility