@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

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

@@ -9,6 +9,12 @@
  * Bodies are unchanged from their previous home; only `export` was added.
  */
 import type { CatalogModel } from "../../codex/catalog";
+import { observeModelCacheRevision } from "../../codex/model-cache";
+import {
+  captureExportConfigAdmission,
+  isExportConfigAdmissionCurrent,
+  type ExportConfigAdmission,
+} from "../../config/admitted-identity";
 import {
   catalogModelSlug,
   filterCatalogVisibleModels,
@@ -28,7 +34,7 @@ import { routedSlug, slugEquals } from "../../providers/slug-codec";
 import type { OcxConfig } from "../../types";
 import { ensureCodexEntitlementFreshness } from "../../codex/model-entitlements";
 import { fetchAllModels } from "./shared";
-import { initialModelSelectionPending } from "../../providers/initial-model-selection";
+import { initialModelSelectionPending, pendingModelSelectionProviders } from "../../providers/initial-model-selection";
 import { catalogFastRowEligible, fastRowId } from "../fast-row";
 import { knownEffortRowIds } from "../effort-row";
 
@@ -77,14 +83,29 @@ export function effectiveManagementDisplayName(
  */
 export async function listManagementModelRows(
   config: OcxConfig,
-  options: { entitlementWaitMs?: number } = {},
+  options: {
+    entitlementWaitMs?: number;
+    models?: readonly CatalogModel[];
+    /** Filled with each provider's content revision as of the moment its rows were chosen. */
+    providerContentRevisions?: Map<string, string>;
+  } = {},
 ): Promise<ManagementModelRow[]> {
-  const [models] = await Promise.all([
-    fetchAllModels(config),
-    ensureCodexEntitlementFreshness(config, {
-      waitMs: options.entitlementWaitMs ?? 3_000,
-    }),
-  ]);
+  /*
+   * A supplied roster skips the gather, and that is the point rather than an optimization.
+   * `fetchAllModels` reaches providers and can persist an initial model selection, which a
+   * read-only caller must not do. Everything below this line is the projection — the disabled
+   * computation, native and account-bound rows, custom rows and the public list — so a caller
+   * that brings its own roster still sees exactly what a writer would, and the two cannot
+   * disagree about the roster for any reason except the roster itself.
+   */
+  const models = options.models === undefined
+    ? (await Promise.all([
+      fetchAllModels(config, options.providerContentRevisions),
+      ensureCodexEntitlementFreshness(config, {
+        waitMs: options.entitlementWaitMs ?? 3_000,
+      }),
+    ]))[0]
+    : [...options.models];
   const disabled = new Set(config.disabledModels ?? []);
   // Native GPT passthrough rows lead (provider "openai", bare-slug namespaced ids): sourced
   // from the static supported set so a disabled model stays listed and re-enableable.
@@ -236,10 +257,201 @@ export function toExportModel(row: ManagementModelRow): ExportModel {
  * tab is absent from `/v1/models` and exporting it would hand the client a
  * selector the proxy refuses to route.
  */
-export async function loadExportModels(config: OcxConfig): Promise<ExportModel[]> {
-  const rows = await listManagementModelRows(config);
+export async function loadExportModels(
+  config: OcxConfig,
+  models?: readonly CatalogModel[],
+): Promise<ExportModel[]> {
+  // Initial selection adopts into the live configuration and persists it, so it has to finish
+  // before anything is admitted. Admitting first would bind this roster to bytes the same load is
+  // about to rewrite, and finalizing against a detached copy would adopt the choices into the copy
+  // while leaving the live configuration pending.
+  if (models === undefined && pendingModelSelectionProviders(config).size > 0) {
+    const { resolvePendingInitialModelSelection } = await import("../../providers/initial-model-selection-runtime");
+    await resolvePendingInitialModelSelection(config);
+  }
+  // The configuration this pass will use from beginning to end, proved to be the one on disk.
+  // Without it there is nothing that may be retained, and the caller still gets its rows: only the
+  // preview authority is withheld.
+  const admission = captureExportConfigAdmission(config);
+  const admitted = admission?.config ?? config;
+  // The gather stamps each provider as it chooses its rows, so the roster and the revisions that
+  // vouch for it come from the same moment. Sampling afterwards would let a concurrent flight's
+  // publication be recorded against rows it never produced.
+  const gathered = new Map<string, string>();
+  // Gathering here rather than through the shared fetch is what keeps the detached copy out of the
+  // initial-selection finalizer: the projection below takes a roster, and that branch performs no
+  // discovery and no configuration write. The entitlement refresh keeps the budget it has always
+  // had, and runs alongside as it did inside the projection.
+  const roster = models === undefined
+    ? (await Promise.all([
+      (await import("../../codex/catalog")).gatherRoutedModels(admitted, { providerContentRevisions: gathered }),
+      ensureCodexEntitlementFreshness(admitted, { waitMs: 3_000 }),
+    ]))[0]
+    : models;
+  const rows = await listManagementModelRows(admitted, { models: roster });
   // Management deliberately lists the full roster so hidden models can be enabled.
   // A client picker must also honor the provider selection, not just its blocklist.
-  const visibleRouted = new Set(filterCatalogVisibleModels(rows.filter(row => !row.native), config));
-  return rows.filter(row => !row.disabled && (row.native || visibleRouted.has(row))).map(toExportModel);
+  const visibleRouted = new Set(filterCatalogVisibleModels(rows.filter(row => !row.native), admitted));
+  const exported = rows.filter(row => !row.disabled && (row.native || visibleRouted.has(row))).map(toExportModel);
+  // Retain the FINAL projection, not an input to it. A preview that rebuilt from raw provider
+  // caches would miss static and forward providers, which never populate one, and would skip the
+  // retention, metadata, combo and filtering this function applies afterwards.
+  // A deep clone, not a frozen view of the caller's array. Freezing the array alone left the model
+  // objects shared, so a caller mutating one in place would have silently rewritten the roster a
+  // later preview plans against, and the fingerprint would have moved with it.
+  // Still the configuration these rows were chosen under, on disk and in hand alike. Revalidating
+  // rather than re-reading an identity is what makes this fail closed: a configuration that moved
+  // during the load leaves no snapshot rather than one recorded under a state its rows never had.
+  if (admission === null || !isExportConfigAdmissionCurrent(admission, config)) {
+    lastExportSnapshot = null;
+    return exported;
+  }
+  // Prefer the revisions the gather stamped; fall back to observing only when the roster was
+  // supplied and no gather happened, where there is nothing tighter to use.
+  const cacheStamp = gathered.size > 0 ? stampFrom(admitted, gathered) : modelCacheStamp(admitted);
+  const retained = lastExportSnapshot;
+  /*
+   * An identical roster keeps the identity it already had.
+   *
+   * The generation moved on every load, so an ordinary read that rebuilt the same rows, which the
+   * Integrations collection does, invalidated a confirmation an operator was in the middle of
+   * submitting. Nothing about the roster had changed; only the counter had. The rows themselves
+   * are compared rather than assumed equal from the configuration and the cache stamp, because a
+   * projection also reads entitlement state neither of those two describes.
+   */
+  const projection = Object.freeze(structuredClone(exported));
+  if (retained !== null
+    && retained.cacheStamp === cacheStamp
+    && isExportConfigAdmissionCurrent(retained.admission, config)
+    && JSON.stringify(retained.models) === JSON.stringify(projection)) {
+    return exported;
+  }
+  lastExportSnapshot = { admission, cacheStamp, generation: ++exportSnapshotGeneration, models: projection };
+  return exported;
+}
+
+/**
+ * The completed export roster from the last ordinary load, if it still describes this config.
+ *
+ * A preview may not gather, so it reads only what an authoritative load already finished. The
+ * admission it carries proved, when the roster was built, that the configuration in hand was the
+ * one on disk; a later read repeats that proof, so a rewritten file, an edited resident object or
+ * a mutated working copy each retire the snapshot rather than letting a preview plan against a
+ * configuration nobody has.
+ *
+ * A cold process has no snapshot and the caller answers a bounded refusal, and an ordinary load
+ * populates one: the Integrations collection read calls `loadExportModels`, so the page an
+ * operator opens before confirming anything is usually the page that fills this in. That is not a
+ * repair for every refusal. A configuration that disagrees with its file keeps refusing however
+ * many times the page is opened, because nothing here reloads or reconciles anything; once the
+ * two agree again the next ordinary read rebuilds the snapshot by itself.
+ */
+let lastExportSnapshot:
+  | { admission: ExportConfigAdmission; cacheStamp: string; generation: number; models: readonly ExportModel[] }
+  | null = null;
+let exportSnapshotGeneration = 0;
+
+/**
+ * A process-local prefix for the roster identity a caller carries between a preview and the
+ * mutation that confirms it.
+ *
+ * The identity used to be the configuration digest with a counter appended, which handed a
+ * dashboard an opaque-looking string that was in fact a fingerprint of the operator's
+ * configuration file. It only has to be unforgeable within this process and distinct across
+ * restarts, so it says nothing about the configuration at all.
+ */
+const rosterIdentityPrefix = `r${Math.trunc(Math.random() * 0xffffffff).toString(36)}`;
+
+function rosterIdentity(generation: number): string {
+  return `${rosterIdentityPrefix}:${generation}`;
+}
+
+/**
+ * Where the gathered half of the roster stands, observed without changing it.
+ *
+ * The config key cannot see a provider's models changing underneath an unchanged configuration,
+ * which is exactly what discovery does. This reads the cache's own generation for each configured
+ * provider through the passive observer, so a completed discovery retires the snapshot and a
+ * preview stops planning against a roster that no longer reflects the provider.
+ */
+function modelCacheStamp(config: OcxConfig): string {
+  return Object.keys(config.providers ?? {})
+    .sort()
+    .map(provider => `${provider}=${observeModelCacheRevision(provider)}`)
+    .join(",");
+}
+
+/**
+ * The same stamp shape, built from revisions the gather recorded rather than from observation.
+ *
+ * A provider the gather did not report falls back to observation so the stamp stays total; that
+ * happens for a provider configured after the rows were chosen, and it retires the snapshot on
+ * the next read rather than pretending the roster covered it.
+ */
+function stampFrom(config: OcxConfig, gathered: ReadonlyMap<string, string>): string {
+  return Object.keys(config.providers ?? {})
+    .sort()
+    .map(provider => `${provider}=${gathered.get(provider) ?? observeModelCacheRevision(provider)}`)
+    .join(",");
+}
+
+/**
+ * Opaque identity of the snapshot a caller is holding, or null when there is none for this config.
+ *
+ * A fingerprint check that rebuilt its own roster could validate against one snapshot while the
+ * mutation wrote from another, because an ordinary load can replace the snapshot at any moment and
+ * nothing about that is serialised against the writer lock. Carrying this identity alongside the
+ * captured roster lets a revalidation prove the snapshot it captured is still the current one
+ * without ever swapping the roster the mutation is about to use.
+ */
+export function exportSnapshotIdentity(config: OcxConfig): string | null {
+  const snapshot = lastExportSnapshot;
+  if (snapshot === null) return null;
+  if (!isExportConfigAdmissionCurrent(snapshot.admission, config)) return null;
+  if (snapshot.cacheStamp !== modelCacheStamp(config)) return null;
+  return rosterIdentity(snapshot.generation);
+}
+
+/** Test seam: a fresh process has no snapshot, and suites must be able to reproduce that. */
+export function resetExportSnapshotForTests(): void {
+  lastExportSnapshot = null;
+}
+
+/**
+ * The export roster for a read that must change nothing at all, or null when there is not one.
+ *
+ * Skipping the initial-selection finalizer was not enough. Discovery itself refreshes credentials
+ * and writes the provider model cache, so a preview that gathered would still be a write dressed
+ * as a read, and "the models list already does this" describes what a GET happens to do rather
+ * than what a preview is allowed to do.
+ *
+ * So this reads already-captured per-provider cache entries and never fetches. When no provider
+ * has a cached roster there is no honest snapshot to plan against, and the caller reports a
+ * bounded refusal rather than triggering a gather to manufacture one.
+ */
+export function previewExportSnapshot(
+  config: OcxConfig,
+): { models: readonly ExportModel[]; identity: string } | null {
+  // One synchronous read of one const. Taking the roster and its identity in two steps let a
+  // concurrent load publish a new snapshot between them, so a caller could hold one roster while
+  // believing it held the identity of another.
+  const snapshot = lastExportSnapshot;
+  if (snapshot === null) return null;
+  // The roster was built from a configuration proved to be the one on disk; this asks whether both
+  // are still that same configuration, and reads nothing but the file to answer.
+  if (!isExportConfigAdmissionCurrent(snapshot.admission, config)) return null;
+  // A completed discovery retires the snapshot: the configuration is unchanged, but the models it
+  // resolves to are not the ones this roster was built from.
+  if (snapshot.cacheStamp !== modelCacheStamp(config)) return null;
+  // Cloned on the way out as well as on the way in. The retained copy is the authority, and a
+  // reader holding its objects could edit the roster every later preview plans against without
+  // going anywhere near this module.
+  return {
+    models: structuredClone(snapshot.models) as readonly ExportModel[],
+    identity: rosterIdentity(snapshot.generation),
+  };
+}
+
+export function previewExportModels(config: OcxConfig): readonly ExportModel[] | null {
+  return previewExportSnapshot(config)?.models ?? null;
 }

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

@@ -38,8 +38,17 @@ export type ExemptionReason =
   | "test-seam"
   /** The CLI reaches the same data through a local transport instead of HTTP. */
   | "local-transport"
+  /** Machine scrape target whose HTTP exposition is the operator contract. */
+  | "scrape-target"
   /** Older clients use this alias; the current CLI drives its declared replacement. */
   | "compatibility-alias"
+  /**
+   * A read-only POST whose purpose is to bind an interactive confirmation to the mutation that
+   * immediately follows it. There is no standalone thing for a CLI to do with one: the plan is
+   * only meaningful to the caller that is about to commit it, and a scripted caller drives the
+   * mutation directly.
+   */
+  | "interactive-preview"
   /** Unreachable in the live dispatch order; delete rather than expose. */
   | "dead"
   /**
@@ -159,6 +168,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/client-integrations/aside/profiles/journal", module: "server/management/aside-profile-routes", mutates: false, mechanism: "prefix-decode" },
   { method: "DELETE", path: "/api/client-integrations/aside/profiles/journal", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode", exempt: { reason: "deferred-verb", why: "Aside history deletion uses the dashboard journal cleanup; the CLI has history and restore but no deletion verb yet.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
   { method: "GET", path: "/api/client-integrations/aside/profiles/{profileId}/journal", module: "server/management/aside-profile-routes", mutates: false, mechanism: "prefix-decode" },
+  { method: "POST", path: "/api/client-integrations/aside/profiles/{profileId}/preview", module: "server/management/aside-profile-routes", mutates: false, mechanism: "prefix-decode", exempt: { reason: "interactive-preview", why: "Plans one Aside profile's change so a dashboard confirmation can show what would change and bind to it. Read-only, and useful only to the caller about to commit; a scripted caller drives the profile toggle or restore directly." } },
   { method: "DELETE", path: "/api/client-integrations/aside/profiles/{profileId}/journal", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode", exempt: { reason: "deferred-verb", why: "Aside profile history deletion uses the dashboard journal cleanup; the CLI has scoped history and restore but no deletion verb yet.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
   { method: "POST", path: "/api/client-integrations/aside/profiles/{profileId}/restore", module: "server/management/aside-profile-routes", mutates: true, mechanism: "prefix-decode" },
   // server/management/codex-prompt-routes
@@ -197,6 +207,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "GET", path: "/api/client-integrations/journal", module: "server/management/integration-routes", mutates: false },
   { method: "DELETE", path: "/api/client-integrations/journal", module: "server/management/integration-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Retiring one rollback row is a dashboard-local cleanup; the CLI verb that would drive it is owed by a later work-phase and is not implemented here.", owner: "260904_priority65_closeout WP7", ownerDoc: "devlog/_fin/260904_priority65_closeout/060_wp7_rollback_journal_crud.md" } },
   { method: "POST", path: "/api/client-integrations/restore", module: "server/management/integration-routes", mutates: true },
+  { method: "POST", path: "/api/client-integrations/preview", module: "server/management/integration-routes", mutates: false, exempt: { reason: "interactive-preview", why: "Plans an apply, overwrite or disable so a dashboard confirmation can show what would change and bind to it. Read-only, and useful only to the caller about to commit; a scripted caller drives PUT /api/client-integrations/{clientId} directly." } },
+  { method: "POST", path: "/api/client-integrations/restore/preview", module: "server/management/integration-routes", mutates: false, exempt: { reason: "interactive-preview", why: "Plans an undo so drift is shown before a restore rather than discovered by a rejected mutation. Read-only, and useful only to the caller about to commit; a scripted caller drives POST /api/client-integrations/restore directly." } },
   // server/management/lab-automation-routes
   { method: "GET", path: "/api/lab/automation", module: "server/management/lab-automation-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
   { method: "GET", path: "/api/lab/automation/runs", module: "server/management/lab-automation-routes", mutates: false, exempt: { reason: "local-transport", why: "ocx lab reads the same rows from the local SQLite projection; src/cli/lab.ts imports ../lab/query directly and never fetches /api/lab." } },
@@ -228,12 +240,20 @@ 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 },
   { method: "POST", path: "/api/storage/trash/restore", module: "server/management/logs-usage-routes", mutates: true },
   { method: "PUT", path: "/api/debug", module: "server/management/logs-usage-routes", mutates: true },
   { method: "PUT", path: "/api/storage/cleanup-policy", module: "server/management/logs-usage-routes", mutates: true },
+  // server/management/metrics-routes
+  { method: "GET", path: "/api/metrics", module: "server/management/metrics-routes", mutates: false, exempt: { reason: "scrape-target", why: "This machine scrape target exposes authenticated text exposition for monitoring systems; a CLI JSON verb would be a different contract." } },
   // server/management/model-routes
   { method: "GET", path: "/api/aliases", module: "server/management/model-routes", mutates: false },
   { method: "GET", path: "/api/catalog", module: "server/management/model-routes", mutates: false },