@bitkyc08/opencodex 2.60.0 → 2.61.0-preview.20260922

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

@@ -1,3 +1,4 @@
+import { persistCommittedDesktopGateway } from "../../claude/desktop-gateway-state";
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../../codex/catalog";
@@ -131,6 +132,17 @@ function persistDesktopProfileField(
   return { ok: true };
 }
 
+async function persistDesktopModeField(
+  config: OcxConfig,
+  desktopMode: "first-party" | "gateway",
+): Promise<{ ok: true } | { ok: false; reason: "missing" | "invalid" | "conflict" }> {
+  const { recordClaudeDesktopMode } = await import("../../claude/desktop-first-party");
+  const outcome = mutatePersistedConfig(persisted => recordClaudeDesktopMode(persisted, desktopMode));
+  if (outcome.status === "unavailable") return { ok: false, reason: outcome.reason };
+  recordClaudeDesktopMode(config, desktopMode);
+  return { ok: true };
+}
+
 export function grokApplyFlightSnapshot(): { currentBytes: number; highWaterBytes: number; active: number } {
   return {
     currentBytes: grokApplyFlight?.bytes ?? 0,
@@ -1002,7 +1014,9 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
   if (url.pathname === "/api/claude-desktop/apply" && req.method === "POST") {
     try {
       // #859: the CLI delegates here so the registry is built in the serving
-      // process. Accept an optional mode; default stays static for back-compat.
+      // process. `mode` selects the Desktop mode: `first-party` (default when the
+      // install has no gateway profile) or `gateway`; the legacy gateway shapes
+      // (static/hybrid/discovery) still select gateway with that library layout.
       let mode: "static" | "hybrid" | "discovery" = "static";
       let parsed: unknown;
       try {
@@ -1011,12 +1025,17 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         rethrowManagementBodyTooLarge(error);
         return jsonResponse({ error: "invalid JSON body" }, 400);
       }
+      const { resolveClaudeDesktopApplyMode, applyDesktopFirstParty, captureDesktopFirstPartyRollback, removeDesktopFirstParty } = await import("../../claude/desktop-first-party");
       const requested = (parsed as { mode?: unknown } | null)?.mode;
+      let desktopMode: "first-party" | "gateway" = resolveClaudeDesktopApplyMode(config);
       if (requested !== undefined) {
         if (requested === "static" || requested === "hybrid" || requested === "discovery") {
           mode = requested;
+          desktopMode = "gateway";
+        } else if (requested === "gateway" || requested === "first-party") {
+          desktopMode = requested;
         } else {
-          return jsonResponse({ error: "mode must be static, hybrid, or discovery" }, 400);
+          return jsonResponse({ error: "mode must be first-party, gateway, static, hybrid, or discovery" }, 400);
         }
       }
       // #859: a delegated CLI apply carries the profile it just saved — the
@@ -1032,6 +1051,60 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
           return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
         }
       }
+      if (desktopMode === "first-party") {
+        const { setIntegrationEnabled } = await import("../../codex/desired-state");
+        const desired = setIntegrationEnabled("claude-desktop", true);
+        if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
+        mirrorDesiredEnabledOntoSnapshot(config, "claude-desktop", true);
+        const { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot } = await import("../../claude/desktop-3p");
+        const rollback = captureDesktopFirstPartyRollback(config);
+        const applied = applyDesktopFirstParty(config);
+        if (!applied.ok) {
+          const { firstPartyRefusalMessage } = await import("./native-integration-routes");
+          return jsonResponse({
+            error: firstPartyRefusalMessage(applied.reason, applied.path),
+            code: "claude_desktop_first_party_refused",
+            reason: applied.reason,
+            path: applied.path,
+          }, applied.reason === "foreign_env" || applied.reason === "intercept_disabled" ? 409 : 500);
+        }
+        // Remove the gateway only after the replacement env was written.
+        const appliedFingerprint = config.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
+        const library = inspectDesktop3pConfigLibrary({ appliedFingerprint });
+        let gatewayRemoved = false;
+        if (library.kind === "gateway_ours" || library.kind === "gateway_drifted") {
+          const removed = (deps.removeDesktop3pStandardPivot ?? removeDesktop3pStandardPivot)({ appliedFingerprint, replaceWhileEnabled: true });
+          if (!removed.ok) {
+            const restored = removed.changed || !applied.changed || rollback();
+            const modeSaved = !removed.changed || (await persistDesktopModeField(config, "first-party")).ok;
+            const warning = [restored ? "" : "first-party settings rollback did not complete",
+              modeSaved ? "" : "first-party is active but its mode marker was not saved"].filter(Boolean).join("; ");
+            return jsonResponse({
+              error: removed.kind === "cleanup_incomplete"
+                ? "Claude Desktop now points at standard mode, but gateway credential cleanup is incomplete; the first-party connection remains active."
+                : "The gateway profile could not be removed safely, so first-party mode was not applied.",
+              code: "claude_desktop_gateway_removal_failed",
+              ...(warning ? { warning } : {}),
+              reason: removed.reason ?? removed.kind,
+              ...(removed.residualPaths ? { residualPaths: removed.residualPaths } : {}),
+            }, removed.kind === "cleanup_incomplete" ? 500 : 409);
+          }
+          gatewayRemoved = removed.changed;
+        }
+        const modeSaved = await persistDesktopModeField(config, "first-party");
+        return jsonResponse({
+          ok: true,
+          mode: "first-party",
+          saved: modeSaved.ok,
+          applied: true,
+          changed: applied.changed || gatewayRemoved,
+          gatewayRemoved,
+          path: applied.path,
+          proxyPort: applied.proxyPort,
+          caCertPath: applied.env.NODE_EXTRA_CA_CERTS,
+          ...(modeSaved.ok ? {} : { warning: `First-party env was applied, but the mode marker was not saved (${modeSaved.reason}).` }),
+        });
+      }
       const { setIntegrationEnabled, claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
       const desired = setIntegrationEnabled("claude-desktop", true);
       if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
@@ -1083,42 +1156,31 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         nativeContextLimits(latest),
       );
       if (!result.written) return jsonResponse({ error: result.reason ?? "Claude Desktop apply failed", saved: true, path: result.path }, 500);
+      const committed = persistCommittedDesktopGateway(config, state.profile, result.fingerprint);
+      const modeWarning = committed.ok ? undefined : `Gateway applied, but its mode/profile state was not saved (${committed.reason}).`;
+      // The durable marker describes the committed gateway even if old-mode cleanup fails.
+      const firstPartyRemoved = removeDesktopFirstParty();
+      if (!firstPartyRemoved.ok) {
+        return jsonResponse({
+          error: `Claude Code settings could not be parsed (${firstPartyRemoved.path}); first-party cleanup remains incomplete after gateway apply.`,
+          code: "claude_desktop_first_party_refused", reason: firstPartyRemoved.reason,
+          applied: true, saved: committed.ok, mode: "gateway", path: result.path,
+          ...(modeWarning ? { warning: modeWarning } : {}),
+        }, 500);
+      }
       const { claudeDesktopPolicyWarning, probeClaudeDesktopPolicy } = await import("../../claude/desktop-policy");
-      const policyState = (deps.probeClaudeDesktopPolicy ?? probeClaudeDesktopPolicy)({
-        platform: deps.platform ?? process.platform,
-      });
+      const policyState = (deps.probeClaudeDesktopPolicy ?? probeClaudeDesktopPolicy)({ platform: deps.platform ?? process.platform });
       const policyWarning = claudeDesktopPolicyWarning(policyState);
-      // Persist applied fingerprint + timestamp so GUI can show saved-vs-applied state.
-      if (result.fingerprint) {
-        // The Desktop write already landed, so a failed bookkeeping save is not
-        // an apply failure: report the miss instead of claiming a clean apply.
-        const marked = persistDesktopProfileField(config, {
-          ...state.profile,
-          appliedFingerprint: result.fingerprint,
-          appliedAt: new Date().toISOString(),
-        });
-        if (!marked.ok) {
-          return jsonResponse({
-            ok: true,
-            applied: true,
-            saved: false,
-            path: result.path,
-            fingerprint: result.fingerprint,
-            warning: [
-              `Claude Desktop was applied, but the applied marker was not saved (${marked.reason}).`,
-              policyWarning,
-            ].filter(Boolean).join(" "),
-          });
-        }
-      }
+      const warning = [modeWarning, policyWarning].filter(Boolean).join(" ");
       return jsonResponse({
         ok: true,
-        saved: true,
+        mode: "gateway",
+        saved: committed.ok,
         applied: true,
         path: result.path,
         fingerprint: result.fingerprint,
         policyState,
-        ...(policyWarning ? { warning: policyWarning } : {}),
+        ...(warning ? { warning } : {}),
       });
     } catch (error) {
       rethrowManagementBodyTooLarge(error);
@@ -1131,21 +1193,39 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
     try {
       const { claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
       const { inspectDesktop3pConfigLibrary } = await import("../../claude/desktop-3p");
+      const { resolveClaudeDesktopApplyMode, inspectDesktopFirstParty } = await import("../../claude/desktop-first-party");
+      const { getClaudeInterceptState } = await import("../../claude/intercept/runtime");
       const persisted = loadConfig();
       const savedFingerprint = persisted.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
       const observed = inspectDesktop3pConfigLibrary({ appliedFingerprint: savedFingerprint });
       const desiredEnabled = claudeDesktopIntegrationEnabled(persisted);
-      const applied = observed.kind === "gateway_ours" || observed.kind === "gateway_drifted";
+      const gatewayApplied = observed.kind === "gateway_ours" || observed.kind === "gateway_drifted";
+      // A gateway profile on disk is what Desktop actually runs, whatever the saved mode says.
+      const mode = gatewayApplied ? "gateway" : resolveClaudeDesktopApplyMode(persisted);
+      const firstPartySeen = inspectDesktopFirstParty(persisted);
+      const intercept = getClaudeInterceptState();
+      const firstParty = {
+        settingsState: firstPartySeen.settings.kind,
+        applied: firstPartySeen.applied,
+        stale: firstPartySeen.stale,
+        interceptEnabled: firstPartySeen.interceptEnabled,
+        interceptRunning: intercept !== null,
+        proxyPort: intercept?.proxyPort ?? firstPartySeen.proxyPort,
+        caCertPath: firstPartySeen.caCertPath,
+      };
+      const applied = mode === "first-party" ? firstPartySeen.applied : gatewayApplied;
       // "Needs update" is only meaningful while the integration is wanted. When the
       // durable switch is OFF, a leftover drifted profile is residue to clear — not
       // a stale apply the operator should refresh.
-      const stale = desiredEnabled && observed.kind === "gateway_drifted";
+      const stale = desiredEnabled && (mode === "first-party" ? firstPartySeen.stale : observed.kind === "gateway_drifted");
       const { getDesktopHealth } = await import("../../claude/desktop-health");
       const { claudeDesktopPolicyHealth, probeClaudeDesktopPolicy } = await import("../../claude/desktop-policy");
       const policyState = (deps.probeClaudeDesktopPolicy ?? probeClaudeDesktopPolicy)({
         platform: deps.platform ?? process.platform,
       });
-      const policy = claudeDesktopPolicyHealth(policyState);
+      // Managed-policy conflicts only matter for the gateway profile; first-party mode never
+      // touches Desktop's own configuration.
+      const policy = claudeDesktopPolicyHealth(mode === "first-party" ? "absent" : policyState);
       const health = {
         ...getDesktopHealth(),
         ok: policy.ok,
@@ -1153,14 +1233,19 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         policy,
       };
       const policyConflict = desiredEnabled && !policy.ok;
-      const baseDrift = desiredEnabled ? !applied || stale : applied || observed.kind === "unsafe";
+      const firstPartyResidue = mode === "gateway" && (firstPartySeen.applied || firstPartySeen.stale);
+      const baseDrift = desiredEnabled
+        ? !applied || stale || firstPartyResidue
+        : applied || gatewayApplied || firstPartySeen.applied || firstPartySeen.stale || observed.kind === "unsafe";
       const driftReason = policyConflict
         ? policy.state === "present" ? "managed_policy_present" : "managed_policy_unknown"
         : desiredEnabled
-          ? !applied ? "desired_on_not_current" : stale ? "profile_drift" : null
-          : applied ? "desired_off_gateway_selected" : null;
+          ? !applied ? "desired_on_not_current" : stale ? "profile_drift" : firstPartyResidue ? "first_party_residue" : null
+          : gatewayApplied ? "desired_off_gateway_selected" : firstPartySeen.applied || firstPartySeen.stale ? "desired_off_first_party_env" : null;
       return jsonResponse({
         desiredEnabled,
+        mode,
+        firstParty,
         installed: observed.kind !== "not_installed",
         observedKind: observed.kind,
         applied,

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

@@ -0,0 +1,77 @@
+import {
+  applyCompanionSettingsPatch,
+  DEFAULT_COMPANION_SETTINGS,
+  loadCompanionSettings,
+  saveCompanionSettings,
+} from "../../companion/settings";
+import { jsonResponse } from "../auth-cors";
+import { openUrl } from "../../lib/open-url";
+import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import type { ManagementContext } from "./context";
+
+let companionPresence: { lastSeenAt: number; kind: "menuBar" | "desktop" } | null = null;
+
+export function resetCompanionPresenceForTests(): void {
+  companionPresence = null;
+}
+
+function response(): Response {
+  const loaded = loadCompanionSettings();
+  return jsonResponse({
+    settings: loaded.settings,
+    updatedAt: loaded.updatedAt,
+    defaults: DEFAULT_COMPANION_SETTINGS,
+    companion: companionPresence ?? { lastSeenAt: null },
+    ...(loaded.corrupt ? { corrupt: true } : {}),
+  });
+}
+
+export async function handleCompanionRoutes(ctx: ManagementContext): Promise<Response | null> {
+  if (ctx.url.pathname === "/api/companion/open-in-browser" && ctx.req.method === "POST") {
+    let body: unknown;
+    try {
+      body = await readManagementJsonBody(ctx.req);
+    } catch (error) {
+      rethrowManagementBodyTooLarge(error);
+      return jsonResponse({ error: "invalid path" }, 400, ctx.req, ctx.config);
+    }
+    const path = body && typeof body === "object" && !Array.isArray(body)
+      ? (body as { path?: unknown }).path
+      : undefined;
+    if (typeof path !== "string" || !path.startsWith("/") || path.startsWith("//") || path.length > 512) {
+      return jsonResponse({ error: "invalid path" }, 400, ctx.req, ctx.config);
+    }
+    const url = `http://127.0.0.1:${ctx.config.port}${path}`;
+    openUrl(url);
+    return jsonResponse({ ok: true, url }, 200, ctx.req, ctx.config);
+  }
+  if (ctx.url.pathname === "/api/companion/settings" && ctx.req.method === "GET") {
+    const userAgent = ctx.req.headers.get("user-agent") ?? "";
+    const kind = userAgent.startsWith("OpenCodexMenuBar/") ? "menuBar"
+      : userAgent.startsWith("OpenCodexDesktop/") ? "desktop"
+      : null;
+    if (kind) companionPresence = { lastSeenAt: Date.now(), kind };
+    return response();
+  }
+  if (ctx.url.pathname !== "/api/companion/settings" || ctx.req.method !== "PUT") return null;
+  let body: unknown;
+  try {
+    body = await readManagementJsonBody(ctx.req);
+  } catch (error) {
+    rethrowManagementBodyTooLarge(error);
+    return jsonResponse({ error: "invalid JSON body" }, 400, ctx.req, ctx.config);
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) return jsonResponse({ error: "invalid settings body" }, 400, ctx.req, ctx.config);
+  const input = body as { reset?: unknown; settings?: unknown };
+  if (input.reset === true) {
+    saveCompanionSettings(DEFAULT_COMPANION_SETTINGS);
+    return response();
+  }
+  if (!("settings" in input)) return jsonResponse({ error: "provide settings or reset:true" }, 400, ctx.req, ctx.config);
+  const current = loadCompanionSettings();
+  if (current.corrupt) return jsonResponse({ error: "Companion settings could not be read; use reset:true to replace them explicitly.", code: "companion_settings_corrupt" }, 409, ctx.req, ctx.config);
+  const updated = applyCompanionSettingsPatch(current.settings, input.settings);
+  if ("error" in updated) return jsonResponse(updated, 400, ctx.req, ctx.config);
+  saveCompanionSettings(updated);
+  return response();
+}

package/src/server/management/logs-usage-routes.ts

@@ -22,6 +22,7 @@ import {
   upsertOAuthProvider,
 } from "../../oauth";
 import { removeCredential } from "../../oauth/store";
+import { getFailureProjection } from "../../usage/failure-projection-cache";
 import { providerDestinationResolvedError } from "../../lib/destination-policy";
 import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
 import { deriveProviderPresets } from "../../providers/derive";
@@ -179,6 +180,24 @@ export async function handleLogsUsageRoutes(ctx: ManagementContext): Promise<Res
   }
 
   if (url.pathname === "/api/usage" && req.method === "GET") {
+    // A sub-resource on the same route rather than a route of its own. It answers a different
+    // question -- which failures keep recurring, rather than what was spent -- and it costs a
+    // ledger scan, so it is opt-in: a dashboard asking for the usage summary must not pay for
+    // a projection it did not ask for.
+    if (url.searchParams.get("failures") === "1") {
+      const projection = await getFailureProjection();
+      return jsonResponse({
+        fingerprintVersion: projection.fingerprintVersion,
+        historyIncomplete: projection.historyIncomplete,
+        unattributedFailures: projection.unattributedFailures,
+        invalidTimestampFailures: projection.invalidTimestampFailures,
+        // Every field here is a closed roster member, a count or a timestamp. The scanner's
+        // checkpoint identity, the configured provider name, the model and the account label
+        // stay internal -- a grouping that promises to carry no content has to keep that
+        // promise at its boundary too.
+        failures: projection.groups,
+      });
+    }
     const range = parseRange(url.searchParams.get("range"));
     const surface = parseUsageSurface(url.searchParams.get("surface"));
     let window: UsageTimeWindow | undefined;

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

@@ -1,3 +1,4 @@
+import { persistCommittedDesktopGateway } from "../../claude/desktop-gateway-state";
 /**
  * Toggle routes for the integrations that are NOT file-merged clients.
  *
@@ -18,13 +19,22 @@
  * 011 (Claude Code), 012 (Grok).
  */
 import { join } from "node:path";
-import { loadConfig, saveConfigPreservingClaudeCode } from "../../config";
+import { loadConfig, mutatePersistedConfig, saveConfigPreservingClaudeCode } from "../../config";
 import { readRuntimePort } from "../../config/process-state";
 import { desktopVisibleNativeSlugs, filterCatalogVisibleModels, nativeContextLimits } from "../../codex/catalog";
 import { getCodexHome } from "../../codex/paths";
 import { providerContextCap } from "../../providers/context-cap";
 import { OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
 import { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot, writeDesktop3pConfig } from "../../claude/desktop-3p";
+import {
+  applyDesktopFirstParty,
+  captureDesktopFirstPartyRollback,
+  inspectDesktopFirstParty,
+  recordClaudeDesktopMode,
+  removeDesktopFirstParty,
+  resolveClaudeDesktopApplyMode,
+  type ClaudeDesktopMode,
+} from "../../claude/desktop-first-party";
 import { projectGrokCatalog } from "../../grok/catalog";
 import { injectGrokConfig, stripGrokConfig } from "../../grok/inject";
 import { inspectGrokConfig } from "../../grok/inspect";
@@ -47,7 +57,9 @@ export type NativeRefusalReason =
   | "write_failed"
   | "metadata_unreadable"
   | "cleanup_incomplete"
-  | "desired_state_changed";
+  | "desired_state_changed"
+  | "foreign_env"
+  | "intercept_disabled";
 
 export interface NativeStatus {
   clientId: NativeIntegrationClientId;
@@ -126,7 +138,7 @@ function desktopStatus(config: ManagementContext["config"]): NativeStatus {
   const seen = inspectDesktop3pConfigLibrary({
     appliedFingerprint: config.claudeCode?.desktopProfile?.appliedFingerprint ?? null,
   });
-  const state: NativeStatus["state"] = seen.kind === "gateway_ours"
+  const gatewayState: NativeStatus["state"] = seen.kind === "gateway_ours"
     ? "current"
     : seen.kind === "unsafe" || seen.kind === "broken" ? "unsafe" : "absent";
   const disableBlocked = seen.kind === "unsafe" || seen.kind === "broken" || seen.kind === "foreign"
@@ -135,6 +147,14 @@ function desktopStatus(config: ManagementContext["config"]): NativeStatus {
         message: "Claude Desktop configuration cannot be changed safely.",
       }
     : null;
+  // First-party mode lives in Claude Code's settings.json, not in Desktop's library. A leftover
+  // gateway profile still counts as current (it is what Desktop is actually running).
+  const firstParty = resolveClaudeDesktopApplyMode(config) === "first-party" && gatewayState === "absent"
+    ? inspectDesktopFirstParty(config)
+    : null;
+  const state: NativeStatus["state"] = firstParty
+    ? firstParty.settings.kind === "unreadable" ? "unsafe" : firstParty.applied ? "current" : "absent"
+    : gatewayState;
   return {
     clientId: "claude-desktop",
     state,
@@ -599,6 +619,28 @@ async function handleGrokToggle(ctx: ManagementContext): Promise<Response> {
   }
 }
 
+export function firstPartyRefusalMessage(
+  reason: "intercept_disabled" | "ca_unavailable" | "unreadable" | "foreign_env",
+  path: string,
+): string {
+  switch (reason) {
+    case "intercept_disabled":
+      return "First-party mode needs the Claude intercept proxy, which is off in this configuration (claudeCode.intercept.enabled / client role). Use gateway mode instead.";
+    case "ca_unavailable":
+      return `The local intercept certificate could not be created (${path}).`;
+    case "unreadable":
+      return `Claude Code settings could not be parsed (${path}); nothing was written.`;
+    case "foreign_env":
+      return `Claude Code settings already set HTTPS_PROXY or NODE_EXTRA_CA_CERTS to a value opencodex does not own (${path}); remove them first or use gateway mode.`;
+  }
+}
+
+/** Record which Desktop mode is applied; `false` when the config file could not be updated. */
+function persistDesktopModeMarker(desktopMode: ClaudeDesktopMode): boolean {
+  const outcome = mutatePersistedConfig(persisted => recordClaudeDesktopMode(persisted, desktopMode));
+  return outcome.status !== "unavailable";
+}
+
 let claudeDesktopToggleFlight: Promise<Response> | null = null;
 
 async function handleClaudeDesktopToggle(ctx: ManagementContext): Promise<Response> {
@@ -626,6 +668,11 @@ async function handleClaudeDesktopToggle(ctx: ManagementContext): Promise<Respon
     const fingerprint = current.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
 
     if (!body.enabled) {
+      const firstPartyRemoved = removeDesktopFirstParty();
+      if (!firstPartyRemoved.ok) {
+        return postCommitRefusal(409, "claude-desktop", "write_failed",
+          `Claude Code settings could not be read (${firstPartyRemoved.path}); the first-party proxy env was left in place.`, { desiredEnabled });
+      }
       const removed = (ctx.deps.removeDesktop3pStandardPivot ?? removeDesktop3pStandardPivot)({ appliedFingerprint: fingerprint });
       if (removed.kind === "cleanup_incomplete") {
         return postCommitRefusal(500, "claude-desktop", "cleanup_incomplete",
@@ -636,9 +683,52 @@ async function handleClaudeDesktopToggle(ctx: ManagementContext): Promise<Respon
         return postCommitRefusal(409, "claude-desktop", removed.reason === "metadata_unreadable" ? "metadata_unreadable" : "write_failed",
           "Claude Desktop configuration could not be changed safely.", { desiredEnabled });
       }
+      const changed = removed.changed || firstPartyRemoved.changed;
+      return jsonResponse({
+        ok: true, clientId: "claude-desktop", changed, state: "absent", desiredEnabled,
+        message: changed ? "Claude Desktop integration disabled." : "Claude Desktop integration is already off.",
+      } satisfies NativeToggleEnvelope);
+    }
+
+    if (resolveClaudeDesktopApplyMode(current) === "first-party") {
+      const rollback = captureDesktopFirstPartyRollback(current);
+      const applied = applyDesktopFirstParty(current);
+      if (!applied.ok) {
+        const reason = applied.reason === "foreign_env" || applied.reason === "intercept_disabled" ? applied.reason : "write_failed";
+        return postCommitRefusal(applied.reason === "unreadable" || applied.reason === "ca_unavailable" ? 500 : 409, "claude-desktop", reason,
+          firstPartyRefusalMessage(applied.reason, applied.path), { desiredEnabled });
+      }
+      const library = inspectDesktop3pConfigLibrary({ appliedFingerprint: fingerprint });
+      let gatewayRemoved = false;
+      if (library.kind === "gateway_ours" || library.kind === "gateway_drifted") {
+        const removed = (ctx.deps.removeDesktop3pStandardPivot ?? removeDesktop3pStandardPivot)({ appliedFingerprint: fingerprint, replaceWhileEnabled: true });
+        if (!removed.ok && !removed.changed && applied.changed && !rollback()) {
+          return postCommitRefusal(500, "claude-desktop", "write_failed",
+            "Gateway cleanup and first-party settings rollback did not complete.", { desiredEnabled });
+        }
+        const partialModeWarning = !removed.ok && removed.changed && !persistDesktopModeMarker("first-party")
+          ? " First-party is active but its mode marker was not saved." : "";
+        if (removed.kind === "cleanup_incomplete") {
+          return postCommitRefusal(500, "claude-desktop", "cleanup_incomplete",
+            "Claude Desktop now points at standard mode, but gateway credential cleanup is incomplete; the first-party connection remains active." + partialModeWarning,
+            { desiredEnabled, residualPaths: removed.residualPaths ?? [] });
+        }
+        if (!removed.ok) {
+          return postCommitRefusal(409, "claude-desktop", removed.reason === "metadata_unreadable" ? "metadata_unreadable" : "write_failed",
+            "The gateway profile could not be removed safely; the mode switch is incomplete." + partialModeWarning, { desiredEnabled });
+        }
+        gatewayRemoved = removed.changed;
+      }
+      const modeSaved = persistDesktopModeMarker("first-party");
+      const changed = applied.changed || gatewayRemoved;
       return jsonResponse({
-        ok: true, clientId: "claude-desktop", changed: removed.changed, state: "absent", desiredEnabled,
-        message: removed.changed ? "Claude Desktop integration disabled." : "Claude Desktop integration is already off.",
+        ok: true, clientId: "claude-desktop", changed, state: "current", desiredEnabled,
+        message: [
+          changed
+            ? "Claude Desktop integration enabled (first-party). Fully quit and reopen Claude Desktop."
+            : "Claude Desktop integration is already on.",
+          modeSaved ? "" : "The first-party mode marker could not be saved to config; status may report the mode as unsaved.",
+        ].filter(Boolean).join(" "),
       } satisfies NativeToggleEnvelope);
     }
 
@@ -665,9 +755,16 @@ async function handleClaudeDesktopToggle(ctx: ManagementContext): Promise<Respon
         nativeContextLimits(latest),
       );
       if (!result.written) return postCommitRefusal(500, "claude-desktop", "write_failed", "Claude Desktop apply failed.", { desiredEnabled: latestDesiredEnabled });
+      const committed = persistCommittedDesktopGateway(ctx.config, latest.claudeCode?.desktopProfile, result.fingerprint);
+      const stateWarning = committed.ok ? "" : " The committed gateway mode/profile state was not saved.";
+      const removed = removeDesktopFirstParty();
+      if (!removed.ok) return postCommitRefusal(500, "claude-desktop", "write_failed", "Gateway applied, but first-party settings cleanup did not complete." + stateWarning, { desiredEnabled: latestDesiredEnabled });
       return jsonResponse({
         ok: true, clientId: "claude-desktop", changed: true, state: "current", desiredEnabled: latestDesiredEnabled,
-        message: "Claude Desktop integration enabled.",
+        message: [
+          "Claude Desktop integration enabled.",
+          stateWarning,
+        ].filter(Boolean).join(" "),
       } satisfies NativeToggleEnvelope);
     } catch {
       return postCommitRefusal(500, "claude-desktop", "write_failed", "Claude Desktop apply failed.", { desiredEnabled });

package/src/server/management/oauth-account-routes.ts

@@ -210,7 +210,7 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
       const { shouldOpenBrowserForLogin } = await import("../../oauth/open-browser-choice");
       if (authUrl && !deviceCode && shouldOpenBrowserForLogin(body.openBrowser, config)) {
         const { openUrl } = await import("../../lib/open-url");
-        openUrl(authUrl);
+        void openUrl(authUrl);
       }
       return jsonResponse({ url: authUrl, instructions, deviceCode });
     } catch (err) {
@@ -869,6 +869,10 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
         name: k.name,
         prefix: k.key.slice(0, 17) + "...",
         createdAt: k.createdAt,
+        // Scope is metadata, not secret: an operator has to be able to read
+        // what a key may reach without minting a replacement to find out.
+        ...(k.allowedProviders ? { allowedProviders: [...k.allowedProviders] } : {}),
+        ...(k.allowedModels ? { allowedModels: [...k.allowedModels] } : {}),
         ...(k.pendingRotation ? { pendingRotation: {
           id: k.pendingRotation.id,
           createdAt: k.pendingRotation.createdAt,
@@ -952,15 +956,49 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     const body = await readJsonBody(req);
     if (!body) return jsonResponse({ error: "invalid body" }, 400, req, config);
     if (typeof body.id !== "string" || !body.id) return jsonResponse({ error: "id required" }, 400, req, config);
-    const nameField = validateKeyName(body.name, { required: true });
-    if ("error" in nameField) return jsonResponse({ error: nameField.error }, 400, req, config);
-    const entry = (config.apiKeys ?? []).find(k => k.id === body.id);
-    if (!entry) return jsonResponse({ error: "key not found" }, 404, req, config);
-    entry.name = nameField.value;
+    const existing = (config.apiKeys ?? []).find(k => k.id === body.id);
+    if (!existing) return jsonResponse({ error: "key not found" }, 404, req, config);
+    const entry = { ...existing };
+    // Rename and scope are independent edits. A scope-only PATCH must not have
+    // to restate the name, and a rename must not silently widen a scope, so
+    // each field is applied only when the caller actually sent it.
+    const renaming = body.name !== undefined;
+    const scopingProviders = body.allowedProviders !== undefined;
+    const scopingModels = body.allowedModels !== undefined;
+    if (!renaming && !scopingProviders && !scopingModels) {
+      return jsonResponse({ error: "name, allowedProviders or allowedModels required" }, 400, req, config);
+    }
+    if (renaming) {
+      const nameField = validateKeyName(body.name, { required: true });
+      if ("error" in nameField) return jsonResponse({ error: nameField.error }, 400, req, config);
+      entry.name = nameField.value;
+    }
+    for (const [field, sent] of [["allowedProviders", scopingProviders], ["allowedModels", scopingModels]] as const) {
+      if (!sent) continue;
+      const value = body[field];
+      // `null` and `[]` both clear the list back to unrestricted; anything else
+      // must be a list of non-empty strings, because a silently ignored malformed
+      // scope would read as "allowed everything" to whoever set it.
+      if (value === null) { delete entry[field]; continue; }
+      if (!Array.isArray(value) || value.some(item => typeof item !== "string" || !item.trim() || item.length > 256)) {
+        return jsonResponse({ error: `${field} must be a list of non-empty names` }, 400, req, config);
+      }
+      const normalized = [...new Set((value as string[]).map(item => item.trim()))];
+      if (normalized.length === 0) delete entry[field];
+      else entry[field] = normalized;
+    }
+    // Publish the validated replacement only after every field is accepted.
+    config.apiKeys = config.apiKeys!.map(key => key === existing ? entry : key);
     saveConfigPreservingClaudeCode(config);
     reconcileLiveStateStores();
     // Never echo key material from a rename.
-    return jsonResponse({ id: entry.id, name: entry.name, createdAt: entry.createdAt }, 200, req, config);
+    return jsonResponse({
+      id: entry.id,
+      name: entry.name,
+      createdAt: entry.createdAt,
+      ...(entry.allowedProviders ? { allowedProviders: [...entry.allowedProviders] } : {}),
+      ...(entry.allowedModels ? { allowedModels: [...entry.allowedModels] } : {}),
+    }, 200, req, config);
   }
 
   if (url.pathname === "/api/keys" && req.method === "DELETE") {

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

@@ -240,6 +240,12 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/storage/trash", module: "server/management/logs-usage-routes", mutates: false },
   { method: "GET", path: "/api/storage/trash/restore/test-stream", module: "server/management/logs-usage-routes", mutates: false, exempt: { reason: "test-seam", why: "Opt-in streaming seam declared at src/storage/restore-job.ts:34." } },
   { 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/companion-routes
+  { method: "POST", path: "/api/companion/open-in-browser", module: "server/management/companion-routes", mutates: true, exempt: { reason: "session-only", why: "Dashboard-only navigation helper; the GUI session opens its current view in the system browser, and there is no standalone CLI operation to drive." } },
+  { method: "GET", path: "/api/companion/settings", module: "server/management/companion-routes", mutates: false },
+  { method: "PUT", path: "/api/companion/settings", module: "server/management/companion-routes", mutates: true },
   { method: "POST", path: "/api/storage/cleanup", module: "server/management/logs-usage-routes", mutates: true },
   { method: "POST", path: "/api/storage/cleanup-policy/run", module: "server/management/logs-usage-routes", mutates: true },
   { method: "POST", path: "/api/storage/cleanup/preview", module: "server/management/logs-usage-routes", mutates: true },