@bitkyc08/opencodex 2.65.0 → 2.66.0-preview.20260925

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

@@ -59,7 +59,7 @@ import {
   setDebugSettings,
   type DebugFlag,
 } from "../../lib/debug-settings";
-import type { OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
+import type { OcxApiKeyEntry, OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
 import { drainAndShutdown } from "../lifecycle";
 import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
 import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
@@ -147,6 +147,45 @@ function validateKeyName(
   return { value };
 }
 
+export type IssuedApiKey = Pick<OcxApiKeyEntry, "id" | "name" | "key" | "createdAt">;
+
+/** Shared one-time data-key issuance used by the dashboard and link transactions. */
+export function issueApiKeyInProcess(config: OcxConfig, name: string): IssuedApiKey {
+  const checked = validateKeyName(name, { required: true });
+  if ("error" in checked) throw new Error(checked.error);
+  const entry: IssuedApiKey = {
+    id: randomUUID(),
+    name: checked.value,
+    key: `ocx_data_${randomBytes(20).toString("hex")}`,
+    createdAt: new Date().toISOString(),
+  };
+  const previous = config.apiKeys;
+  config.apiKeys = [...(previous ?? []), entry];
+  try {
+    saveConfigPreservingClaudeCode(config);
+    reconcileLiveStateStores();
+  } catch (error) {
+    config.apiKeys = previous;
+    throw error;
+  }
+  return entry;
+}
+
+/** Revoke and persist one data key; callers can retain their own record on false. */
+export function revokeApiKeyInProcess(config: OcxConfig, id: string): boolean {
+  const before = config.apiKeys ?? [];
+  if (!before.some(key => key.id === id)) return false;
+  config.apiKeys = before.filter(key => key.id !== id);
+  try {
+    saveConfigPreservingClaudeCode(config);
+    reconcileLiveStateStores();
+  } catch (error) {
+    config.apiKeys = before;
+    throw error;
+  }
+  return true;
+}
+
 function metaMuseConsentRequired(provider: string, principal: ManagementContext["principal"]): Response | null {
   if (provider !== "meta-muse" || principal === "gui-session") return null;
   return jsonResponse({
@@ -955,16 +994,7 @@ export async function handleOauthAccountRoutes(ctx: ManagementContext): Promise<
     const nameField = validateKeyName(body.name, { required: false });
     if ("error" in nameField) return jsonResponse({ error: nameField.error }, 400, req, config);
     const name = nameField.value || "default";
-    // A direct random draw. The previous derivation hashed every configured
-    // provider API key into the input, which was never needed for uniqueness and
-    // made this secret's safety argument depend on string concatenation rather
-    // than the RNG. 20 bytes is the same 40 hex characters as before, so nothing
-    // that pattern-matches the key shape changes.
-    const key = "ocx_data_" + randomBytes(20).toString("hex");
-    const entry = { id: randomUUID(), name, key, createdAt: new Date().toISOString() };
-    config.apiKeys = [...(config.apiKeys ?? []), entry];
-    saveConfigPreservingClaudeCode(config);
-    reconcileLiveStateStores();
+    const entry = issueApiKeyInProcess(config, name); // shared helper uses randomBytes(20)
     return jsonResponse({ id: entry.id, name: entry.name, key: entry.key, createdAt: entry.createdAt }, 201, req, config);
   }
 
@@ -1021,12 +1051,8 @@ 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 before = (config.apiKeys ?? []).length;
-    config.apiKeys = (config.apiKeys ?? []).filter(k => k.id !== body.id);
     // A stale id must not read as a successful revocation.
-    if (config.apiKeys.length === before) return jsonResponse({ error: "key not found" }, 404, req, config);
-    saveConfigPreservingClaudeCode(config);
-    reconcileLiveStateStores();
+    if (!revokeApiKeyInProcess(config, body.id)) return jsonResponse({ error: "key not found" }, 404, req, config);
     return jsonResponse({ success: true }, 200, req, config);
   }
   return null;

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

@@ -0,0 +1,159 @@
+/**
+ * Protocol vocabulary and request-path preview for the dashboard.
+ *
+ * Loaded on demand from src/server/management-api.ts, like the other optional namespaces:
+ * the planner reaches the router and the ingress eligibility rules, and a static import
+ * would put them on every dashboard request.
+ *
+ * GET (optionally with `?provider=<name>`, src/protocols/provider-summary.ts) and the plan
+ * preview are read-only. The preview is computed from config alone
+ * (src/protocols/plan-snapshot.ts): it sends nothing upstream, advances no combo state, and
+ * never logs its input. PATCH /api/protocols/settings is the one writer; it validates in
+ * src/server/management/protocol-settings-patch.ts, persists through the locked
+ * saveConfigPreservingClaudeCode, and answers with the fresh GET shape. Authentication is
+ * inherited from the management chain.
+ */
+import { jsonResponse } from "../auth-cors";
+import { isProtocol, PROTOCOL_CONTRACT_VERSION } from "../../protocols/contract";
+import { isProtocolFeature, PROTOCOL_FEATURES, type ProtocolFeature } from "../../protocols/features";
+import { previewProtocolPlan, type ProtocolPlanRequest } from "../../protocols/plan-snapshot";
+import { buildProtocolProviderSummary } from "../../protocols/provider-summary";
+import { protocolPolicyRevision, resolveApiSurfaceSettings, resolveProtocolSettings } from "../../protocols/settings";
+import type { OcxConfig } from "../../types";
+import type { ManagementContext } from "./context";
+import { readManagementJsonBodyOr } from "./body";
+import {
+  applyProtocolSettingsPatch,
+  parseProtocolSettingsPatch,
+  restoreProtocolSettings,
+  snapshotProtocolSettings,
+} from "./protocol-settings-patch";
+
+export const PROTOCOL_PLAN_LIMITS = { modelLength: 200, features: 24 } as const;
+export const PROTOCOL_PROVIDER_QUERY_LIMIT = 200;
+
+const PLAN_BODY_KEYS = new Set(["model", "inbound", "features"]);
+const INVALID_BODY = Symbol("invalid-body");
+
+type ParsedPlanBody = { ok: true; request: ProtocolPlanRequest } | { ok: false; code: string; message: string };
+
+function invalid(code: string, message: string): ParsedPlanBody {
+  return { ok: false, code, message };
+}
+
+/** Validate a plan request body. Messages name the field, never echo its value. */
+export function parseProtocolPlanBody(body: unknown): ParsedPlanBody {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return invalid("invalid_body", "body must be a JSON object");
+  const record = body as Record<string, unknown>;
+  for (const key of Object.keys(record)) {
+    if (!PLAN_BODY_KEYS.has(key)) return invalid("unknown_field", "body accepts only model, inbound and features");
+  }
+  const model = typeof record.model === "string" ? record.model.trim() : "";
+  if (!model || model.length > PROTOCOL_PLAN_LIMITS.modelLength || /[\u0000-\u001f\u007f]/.test(model)) {
+    return invalid("invalid_model", `model must be a non-empty string of at most ${PROTOCOL_PLAN_LIMITS.modelLength} characters`);
+  }
+  if (!isProtocol(record.inbound)) return invalid("invalid_inbound", "inbound must be responses, chat or messages");
+  let features: ProtocolFeature[] = [];
+  if (record.features !== undefined) {
+    if (!Array.isArray(record.features) || record.features.length > PROTOCOL_PLAN_LIMITS.features) {
+      return invalid("invalid_features", `features must be an array of at most ${PROTOCOL_PLAN_LIMITS.features} entries`);
+    }
+    if (!record.features.every(isProtocolFeature)) return invalid("invalid_features", "features contains an unknown feature");
+    features = [...new Set(record.features)];
+  }
+  return { ok: true, request: { model, inbound: record.inbound, features } };
+}
+
+function protocolInfo(config: OcxConfig) {
+  return {
+    schemaVersion: 1,
+    contractVersion: PROTOCOL_CONTRACT_VERSION,
+    policyRevision: protocolPolicyRevision(config),
+    surfaces: resolveApiSurfaceSettings(config),
+    settings: resolveProtocolSettings(config),
+    features: PROTOCOL_FEATURES,
+  };
+}
+
+/**
+ * `GET /api/protocols?provider=<name>`: the usual body plus the provider's wire summary. The
+ * name is bounded and must name a configured provider; neither error echoes it back.
+ */
+function protocolInfoForProvider(ctx: ManagementContext, values: string[]): Response {
+  const { req, config } = ctx;
+  const name = values.length === 1 ? values[0]!.trim() : "";
+  if (!name || name.length > PROTOCOL_PROVIDER_QUERY_LIMIT || /[\u0000-\u001f\u007f]/.test(name)) {
+    const message = `provider must be one non-empty name of at most ${PROTOCOL_PROVIDER_QUERY_LIMIT} characters`;
+    return jsonResponse({ error: { code: "invalid_provider", message } }, 400, req, config);
+  }
+  const provider = buildProtocolProviderSummary(config, name);
+  if (!provider) return jsonResponse({ error: { code: "unknown_provider", message: "no provider with that name" } }, 404, req, config);
+  return jsonResponse({ ...protocolInfo(config), provider }, 200, req, config);
+}
+
+/** Only SQLITE_BUSY is contention worth retrying; any other lock failure repeats forever. */
+function isConfigLockContention(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  if ((error as { code?: unknown }).code !== "CONFIG_MUTATION_LOCK_UNAVAILABLE") return false;
+  return (error as { cause?: { code?: unknown } }).cause?.code === "SQLITE_BUSY";
+}
+
+async function patchProtocolSettings(ctx: ManagementContext): Promise<Response> {
+  const { req, config } = ctx;
+  const body = await readManagementJsonBodyOr(req, INVALID_BODY);
+  const parsed = body === INVALID_BODY
+    ? { ok: false as const, code: "invalid_json", message: "body must be valid JSON" }
+    : parseProtocolSettingsPatch(body);
+  if (!parsed.ok) return jsonResponse({ error: { code: parsed.code, message: parsed.message } }, 400, req, config);
+
+  const snapshot = snapshotProtocolSettings(config);
+  const applied = applyProtocolSettingsPatch(config, parsed.patch);
+  if (!applied.ok) {
+    restoreProtocolSettings(config, snapshot);
+    return jsonResponse({ error: { code: applied.code, message: applied.message } }, 400, req, config);
+  }
+  // `deps.` first: route tests with an in-memory fixture must never write the real config.
+  const persist = ctx.deps.saveConfigPreservingClaudeCode
+    ?? (await import("../../config")).saveConfigPreservingClaudeCode;
+  try {
+    persist(config);
+  } catch (error) {
+    // Undo in memory too: a live config that serves a state the file does not hold would
+    // reopen (or keep closed) the surface only until the next restart.
+    restoreProtocolSettings(config, snapshot);
+    return isConfigLockContention(error)
+      ? jsonResponse({ error: { code: "config_busy", message: "Another process is saving the configuration. Try again in a moment." } }, 409, req, config)
+      : jsonResponse({ error: { code: "write_failed", message: "The configuration could not be saved." } }, 500, req, config);
+  }
+  // Closing Messages also turned the Claude integration off; prune its agent definitions the
+  // way the Claude page toggle does.
+  if (applied.claudeCodeChanged) await ctx.syncClaudeAgentDefsBestEffort?.();
+  return jsonResponse(protocolInfo(config), 200, req, config);
+}
+
+export async function handleProtocolRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { url, req, config } = ctx;
+
+  if (url.pathname === "/api/protocols") {
+    if (req.method !== "GET") return null;
+    if (!url.searchParams.has("provider")) return jsonResponse(protocolInfo(config), 200, req, config);
+    return protocolInfoForProvider(ctx, url.searchParams.getAll("provider"));
+  }
+
+  if (url.pathname === "/api/protocols/settings") {
+    if (req.method !== "PATCH") return null;
+    return patchProtocolSettings(ctx);
+  }
+
+  if (url.pathname === "/api/protocols/plan") {
+    if (req.method !== "POST") return null;
+    const body = await readManagementJsonBodyOr(req, INVALID_BODY);
+    const parsed = body === INVALID_BODY ? invalid("invalid_json", "body must be valid JSON") : parseProtocolPlanBody(body);
+    if (!parsed.ok) {
+      return jsonResponse({ error: { code: parsed.code, message: parsed.message } }, 400, req, config);
+    }
+    return jsonResponse(previewProtocolPlan(config, parsed.request), 200, req, config);
+  }
+
+  return null;
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Validation and in-memory application of `PATCH /api/protocols/settings`.
+ *
+ * Pure with respect to I/O: the route persists through `saveConfigPreservingClaudeCode` and
+ * restores the snapshot taken here when the save fails, so a refused write never leaves the
+ * live config serving a state the file does not hold.
+ *
+ * The one asymmetric rule is the Messages surface. Closing it writes
+ * `apiSurfaces.messages.enabled = false` AND `claudeCode.enabled = false` in the same save:
+ * a binary older than `apiSurfaces` reads only `claudeCode.enabled`, so a rollback after a
+ * close must still find the endpoint closed. Opening writes only the explicit surface value;
+ * an older binary then keeps reading `claudeCode.enabled`, which errs closed.
+ */
+import { commitClaudeCodeBlock } from "../../claude/claude-code-block";
+import type { ProtocolRolloutSettings, UnrepresentablePolicy } from "../../protocols/settings";
+import type { OcxConfig } from "../../types";
+
+export interface ProtocolSettingsPatch {
+  messagesEnabled?: boolean;
+  unrepresentable?: UnrepresentablePolicy;
+  rollout?: Partial<ProtocolRolloutSettings>;
+}
+
+export type ParsedProtocolSettingsPatch =
+  | { ok: true; patch: ProtocolSettingsPatch }
+  | { ok: false; code: string; message: string };
+
+const PATCH_KEYS = new Set(["messagesEnabled", "unrepresentable", "rollout"]);
+export const PROTOCOL_ROLLOUT_KEYS = [
+  "nativeChatCombos",
+  "managedMessagesNative",
+  "managedMessagesNativeOAuth",
+  "directEncoders",
+  "shadowPlan",
+] as const satisfies readonly (keyof ProtocolRolloutSettings)[];
+const ROLLOUT_KEYS = new Set<string>(PROTOCOL_ROLLOUT_KEYS);
+
+type Rec = Record<string, unknown>;
+function isRec(value: unknown): value is Rec {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function invalid(code: string, message: string): ParsedProtocolSettingsPatch {
+  return { ok: false, code, message };
+}
+
+/** Strict: unknown keys and wrong types are refused; messages name the field, never the value. */
+export function parseProtocolSettingsPatch(body: unknown): ParsedProtocolSettingsPatch {
+  if (!isRec(body)) return invalid("invalid_body", "body must be a JSON object");
+  const keys = Object.keys(body);
+  if (keys.length === 0) return invalid("empty_body", "body must set messagesEnabled, unrepresentable or rollout");
+  for (const key of keys) {
+    if (!PATCH_KEYS.has(key)) return invalid("unknown_field", "body accepts only messagesEnabled, unrepresentable and rollout");
+  }
+  const patch: ProtocolSettingsPatch = {};
+  if (body.messagesEnabled !== undefined) {
+    if (typeof body.messagesEnabled !== "boolean") return invalid("invalid_messages_enabled", "messagesEnabled must be a boolean");
+    patch.messagesEnabled = body.messagesEnabled;
+  }
+  if (body.unrepresentable !== undefined) {
+    if (body.unrepresentable !== "legacy" && body.unrepresentable !== "reject") {
+      return invalid("invalid_unrepresentable", "unrepresentable must be \"legacy\" or \"reject\"");
+    }
+    patch.unrepresentable = body.unrepresentable;
+  }
+  if (body.rollout !== undefined) {
+    if (!isRec(body.rollout)) return invalid("invalid_rollout", "rollout must be an object");
+    const rollout: Partial<ProtocolRolloutSettings> = {};
+    for (const [key, value] of Object.entries(body.rollout)) {
+      if (!ROLLOUT_KEYS.has(key)) return invalid("unknown_rollout_field", `rollout accepts only ${PROTOCOL_ROLLOUT_KEYS.join(", ")}`);
+      if (typeof value !== "boolean") return invalid("invalid_rollout", "rollout values must be booleans");
+      rollout[key as keyof ProtocolRolloutSettings] = value;
+    }
+    patch.rollout = rollout;
+  }
+  return { ok: true, patch };
+}
+
+/** The config subtrees a patch may touch, captured so a failed save can be undone. */
+export interface ProtocolSettingsSnapshot {
+  apiSurfaces: unknown;
+  protocols: unknown;
+  claudeCode: unknown;
+}
+
+export function snapshotProtocolSettings(config: OcxConfig): ProtocolSettingsSnapshot {
+  return {
+    apiSurfaces: structuredClone(config.apiSurfaces),
+    protocols: structuredClone(config.protocols),
+    claudeCode: structuredClone(config.claudeCode),
+  };
+}
+
+export function restoreProtocolSettings(config: OcxConfig, snapshot: ProtocolSettingsSnapshot): void {
+  const target = config as unknown as Rec;
+  for (const key of ["apiSurfaces", "protocols", "claudeCode"] as const) {
+    if (snapshot[key] === undefined) delete target[key];
+    else target[key] = snapshot[key];
+  }
+}
+
+export type ApplyProtocolSettingsResult =
+  | { ok: true; claudeCodeChanged: boolean }
+  | { ok: false; code: string; message: string };
+
+/**
+ * Apply a validated patch to the live config. Checks that depend on the merged state run
+ * before anything is written, so a refusal leaves the config untouched.
+ */
+export function applyProtocolSettingsPatch(config: OcxConfig, patch: ProtocolSettingsPatch): ApplyProtocolSettingsResult {
+  const protocols: Rec = isRec(config.protocols) ? { ...config.protocols } : {};
+  if (patch.rollout) {
+    const rollout: Rec = { ...(isRec(protocols.rollout) ? protocols.rollout : {}), ...patch.rollout };
+    // The OAuth extension is meaningless without the key-auth lane it extends; the resolver
+    // would silently read it as off, so refuse turning it on alone instead of storing a switch
+    // that does nothing. Turning the key-auth lane off leaves the extension inert, not wrong.
+    if (patch.rollout.managedMessagesNativeOAuth === true && rollout.managedMessagesNative !== true) {
+      return {
+        ok: false,
+        code: "rollout_dependency",
+        message: "rollout.managedMessagesNativeOAuth requires rollout.managedMessagesNative",
+      };
+    }
+    protocols.rollout = rollout;
+  }
+  if (patch.unrepresentable !== undefined) protocols.unrepresentable = patch.unrepresentable;
+  if (patch.unrepresentable !== undefined || patch.rollout) {
+    config.protocols = protocols as OcxConfig["protocols"];
+  }
+
+  let claudeCodeChanged = false;
+  if (patch.messagesEnabled !== undefined) {
+    // A malformed block is replaced, not merged: the explicit value is what the operator asked for.
+    const surfaces: Rec = isRec(config.apiSurfaces) ? { ...config.apiSurfaces } : {};
+    const messages: Rec = isRec(surfaces.messages) ? { ...surfaces.messages } : {};
+    messages.enabled = patch.messagesEnabled;
+    surfaces.messages = messages;
+    config.apiSurfaces = surfaces as OcxConfig["apiSurfaces"];
+    if (!patch.messagesEnabled && config.claudeCode?.enabled !== false) {
+      commitClaudeCodeBlock(config, { ...(config.claudeCode ?? {}), enabled: false });
+      claudeCodeChanged = true;
+    }
+  }
+  return { ok: true, claudeCodeChanged };
+}

package/src/server/management/provider-patch-transaction.ts

@@ -0,0 +1,61 @@
+import type { OcxConfig } from "../../types";
+import { withConfigMutationLockSync } from "../../config/mutation-lock";
+import { captureConfigTopLevelRollback } from "../../config/rebase-provenance";
+import { ConfigWritePublishedError } from "../../config/persist-unlocked";
+
+/**
+ * Persistence rebases nested records and arrays in place before writing. Keep their
+ * identities and descriptors so a failed write also restores references held by routing.
+ * Only plain config containers are traversed; opaque runtime values and accessors are
+ * retained as descriptors, never cloned or invoked while taking the snapshot.
+ */
+function captureConfigGraphRollback(config: OcxConfig): () => void {
+  const snapshots = new Map<object, PropertyDescriptorMap>();
+  const visit = (value: unknown): void => {
+    if (value === null || typeof value !== "object" || snapshots.has(value)) return;
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) return;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    snapshots.set(value, descriptors);
+    for (const key of Reflect.ownKeys(descriptors)) {
+      const descriptor = descriptors[key as keyof typeof descriptors]!;
+      if ("value" in descriptor) visit(descriptor.value);
+    }
+  };
+  visit(config);
+  const restoreProvenance = captureConfigTopLevelRollback(config, []);
+  return () => {
+    for (const [value, descriptors] of snapshots) {
+      const keys = Reflect.ownKeys(value);
+      const originalKeys = Reflect.ownKeys(descriptors);
+      // Re-defining a deleted provider appends it, changing route tie-breaking.
+      // Rebuild record properties in snapshot order; array indices/length retain
+      // their descriptor-based restoration and every container keeps its identity.
+      const reordered = !Array.isArray(value)
+        && (keys.length !== originalKeys.length || keys.some((key, index) => key !== originalKeys[index]));
+      for (const key of keys) {
+        if (reordered || !Object.hasOwn(descriptors, key)) Reflect.deleteProperty(value, key);
+      }
+      Object.defineProperties(value, descriptors);
+    }
+    restoreProvenance();
+  };
+}
+
+/** No await may separate mutation, persistence, and rollback inside this lock. */
+export function commitProviderPatch(
+  config: OcxConfig,
+  mutate: () => void,
+  save: (config: OcxConfig) => void,
+): void {
+  withConfigMutationLockSync(() => {
+    const rollback = captureConfigGraphRollback(config);
+    try {
+      mutate();
+      save(config);
+    } catch (error) {
+      if (!(error instanceof ConfigWritePublishedError)) rollback();
+      throw error;
+    }
+  });
+}

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

@@ -36,6 +36,7 @@ import {
   submitManualLoginCode,
   upsertOAuthProvider,
 } from "../../oauth";
+import { commitProviderPatch } from "./provider-patch-transaction";
 import { captureConfigTopLevelRollback } from "../../config/rebase-provenance";
 import { canonicalAutoReviewModelKey, mergeModelPinnedEfforts, modelPinnedEffortsConfigError, pinnedReasoningEffortConfigError } from "../../config/provider-validation";
 import { replaceProviderAccountSet } from "../../oauth/store";
@@ -73,6 +74,7 @@ import { clearAccountQuotaCache, clearProviderQuotaCache, fetchProviderQuotaRepo
 import { getCachedProviderRoutingQuota } from "../../providers/quota-routing-cache";
 import { PROVIDER_QUOTA_MAX_AGE_MS, type ProviderRoutingQuota } from "../../providers/quota-types";
 import { cachedProviderQuotaIsExhausted } from "../../combos/resolve";
+import { resolveJevDecision } from "../../combos/jev";
 import { clearKeyCooldowns, forgetApiKeyRotationCursor } from "../../providers/key-failover";
 import { providerRequestPacingStatus } from "../../providers/request-pacing";
 import { CODEX_FORWARD_BASE_URL, isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
@@ -1423,9 +1425,9 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       if (!provider || !isCanonicalOpenAiForwardProvider(provider)) {
         return jsonResponse({ error: "provider openai must be the canonical built-in provider" }, 400);
       }
-      const { saveConfigPreservingClaudeCode: save } = await import("../../config");
-      config.providers.openai = { ...provider, codexAccountMode: mode };
-      save(config);
+      commitProviderPatch(config, () => {
+        config.providers.openai = { ...provider, codexAccountMode: mode };
+      }, deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode);
       reconcileLiveStateStores();
       (deps.clearProviderQuotaCache ?? clearProviderQuotaCache)();
       (deps.clearThreadAccountMap ?? clearThreadAccountMap)();
@@ -1450,9 +1452,9 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       if (config.providers[name]!.disabled) {
         return jsonResponse({ error: "cannot set a disabled provider as default", code: "default_provider_disabled" }, 400);
       }
-      const { saveConfigPreservingClaudeCode: save } = await import("../../config");
-      config.defaultProvider = name;
-      save(config);
+      commitProviderPatch(config, () => {
+        config.defaultProvider = name;
+      }, deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode);
       reconcileLiveStateStores();
       return jsonResponse({ success: true, name, defaultProvider: name });
     }
@@ -1557,19 +1559,9 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
         const validation = validateConfigCandidate({ ...config, providers: { ...config.providers, [name]: candidate } });
         if (!validation.ok) { replayError = validation.error; return; }
       }
-      const previous = Object.getOwnPropertyDescriptor(config.providers, name);
-      const rollback = pinsTouched ? captureConfigTopLevelRollback(config, []) : undefined;
-      try {
+      commitProviderPatch(config, () => {
         config.providers[name] = candidate;
-        (deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode)(config);
-      } catch (error) {
-        if (rollback) {
-          if (previous) Object.defineProperty(config.providers, name, previous);
-          else delete config.providers[name];
-          rollback();
-        }
-        throw error;
-      }
+      }, deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode);
     });
     if (replayError !== undefined) return jsonResponse({ error: replayError }, 409);
     reconcileLiveStateStores();
@@ -1611,6 +1603,35 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
         message: "Passthrough provider is configured (forwards your Codex login; no upstream /models).",
       });
     }
+    if (name === "jev" && providerMatchesRegistryTransport(name, prov)) {
+      const probe = { targetKey: "jev/probe", effort: null } as const;
+      const decision = await resolveJevDecision({
+        body: { input: "Verify the configured TypeSafe JEV decision service." },
+        candidates: [{
+          key: probe.targetKey,
+          provider: "jev",
+          model: "jev-latest",
+          reasoningEfforts: [],
+        }],
+        fallback: probe,
+        config,
+        signal: req.signal,
+      });
+      if (decision.gate === "apply") {
+        return jsonResponse({
+          ok: true,
+          latencyMs: decision.latencyMs,
+          message: "Connected. TypeSafe JEV answered a decision probe.",
+        });
+      }
+      return jsonResponse({
+        ok: false,
+        latencyMs: decision.latencyMs,
+        error: decision.gate === "missing_key"
+          ? "TypeSafe JEV API key is not configured"
+          : `TypeSafe JEV decision probe failed (${decision.gate})`,
+      });
+    }
     if (prov.liveModels === false) {
       // A static catalog has no live discovery endpoint to test. This is neither
       // positive connectivity evidence nor an outage, and it must stay before

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

@@ -337,6 +337,9 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   // server/management/quota-reset-routes
   { method: "GET", path: "/api/quota-resets", module: "server/management/quota-reset-routes", mutates: false, mechanism: "negated-guard" },
   // server/management/workflow-budget-routes
+  { method: "GET", path: "/api/protocols", module: "server/management/protocol-routes", mutates: false },
+  { method: "POST", path: "/api/protocols/plan", module: "server/management/protocol-routes", mutates: false },
+  { method: "PATCH", path: "/api/protocols/settings", module: "server/management/protocol-routes", mutates: true },
   { method: "GET", path: "/api/workflow-budget", module: "server/management/workflow-budget-routes", mutates: false, exempt: { reason: "deferred-verb", why: "Reading a root's live budget is owed a CLI verb -- an operator staring at a 429 is usually already in a terminal -- but the ledger is process memory with no local transport to read it through, so the verb has to be an HTTP call the CLI does not yet make.", owner: "260915_workflow_budget_window wfc", ownerDoc: "devlog/_plan/260915_workflow_budget_window/030_wfc_diff_plan.md" } },
   { method: "POST", path: "/api/workflow-budget/clear", module: "server/management/workflow-budget-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Clearing one root is owed the same verb as the read above and for the same reason. It is deliberately not shipped as a verb in this work-phase: the read comes first, because an operator who cannot see which ceiling fired has no basis for deciding to forgive it.", owner: "260915_workflow_budget_window wfc", ownerDoc: "devlog/_plan/260915_workflow_budget_window/030_wfc_diff_plan.md" } },
   // server/management/request-history-routes
@@ -363,6 +366,15 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "POST", path: "/api/storage/codex-logs/protect", module: "server/management/storage-log-guard-routes", mutates: true },
   { method: "POST", path: "/api/storage/codex-logs/repair", module: "server/management/storage-log-guard-routes", mutates: true },
   { method: "POST", path: "/api/storage/codex-logs/unprotect", module: "server/management/storage-log-guard-routes", mutates: true },
+  // server/management/link-routes
+  { method: "GET", path: "/api/link/status", module: "server/management/link-routes", mutates: false },
+  { method: "GET", path: "/api/link/candidates", module: "server/management/link-routes", mutates: false, exempt: { reason: "session-only", why: "SSH candidates are a dashboard pairing surface and are withheld from admin-token and Tailscale identity sessions." } },
+  { method: "POST", path: "/api/link/probe", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "SSH probing and host-key presentation are part of the interactive pairing consent flow." } },
+  { method: "POST", path: "/api/link/confirm-host", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "Persisting a host key requires the paired dashboard session that saw the fingerprint." } },
+  { method: "POST", path: "/api/link/join", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "Joining a confirmed Home issues a link credential and restarts this standalone runtime as a client." } },
+  { method: "POST", path: "/api/link/apply", module: "server/management/link-routes", mutates: true, exempt: { reason: "session-only", why: "Applying a link issues a data key and starts a remote tunnel, so it requires the paired dashboard session." } },
+  { method: "DELETE", path: "/api/link/{id}", module: "server/management/link-routes", mutates: true, mechanism: "regex" },
+  { method: "POST", path: "/api/link/issue", module: "server/management/link-routes", mutates: true },
   // server/management/remote-workspace-routes
   { method: "GET", path: "/api/remote-workspace", module: "server/management/remote-workspace-routes", mutates: false, exempt: { reason: "deferred-verb", why: "The first Remote Workspace slice exposes Hub status through the authenticated dashboard; a distinct CLI Hub-status verb is still owed and must not be confused with the Executor-local status command.", owner: "remote-workspace-cli-followup", ownerDoc: "docs-site/src/content/docs/reference/management-api.md" } },
   { method: "GET", path: "/api/remote-workspace/runtimes", module: "server/management/remote-workspace-routes", mutates: false, exempt: { reason: "deferred-verb", why: "The first Remote Workspace slice exposes Hub runtime availability through the authenticated dashboard; a distinct CLI Hub-status verb is still owed.", owner: "remote-workspace-cli-followup", ownerDoc: "docs-site/src/content/docs/reference/management-api.md" } },

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

@@ -24,6 +24,7 @@
  * gate accepts only after matching origin and the per-session CSRF token.
  */
 import { jsonResponse } from "../auth-cors";
+import { verifyLocalDesktopSnapshotBody } from "../local-desktop-snapshot-auth";
 import { agentDrivenMarkers } from "../../cli/agent-driven";
 import type { ManagementContext } from "./context";
 
@@ -102,8 +103,8 @@ export async function handleSidebarRoutes(ctx: ManagementContext): Promise<Respo
     if (req.headers.has("origin")) {
       return Response.json({ error: "desktop snapshot does not accept browser-origin requests" }, { status: 403 });
     }
-    if (ctx.principal !== "admin-token") {
-      return jsonResponse({ error: "desktop snapshot requires admin token" }, 403, req, ctx.config);
+    if (ctx.principal !== "admin-token" && ctx.principal !== "local-desktop-snapshot-capability") {
+      return jsonResponse({ error: "desktop snapshot requires admin token or snapshot capability" }, 403, req, ctx.config);
     }
     if (req.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() !== "application/json") {
       return jsonResponse({ error: "invalid desktop snapshot" }, 400, req, ctx.config);
@@ -127,7 +128,11 @@ export async function handleSidebarRoutes(ctx: ManagementContext): Promise<Respo
         bytes.set(part.value, used);
         used += part.value.length;
       }
-      const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, used));
+      const body = bytes.subarray(0, used);
+      if (ctx.principal === "local-desktop-snapshot-capability" && !verifyLocalDesktopSnapshotBody(req, body)) {
+        return jsonResponse({ error: "invalid desktop snapshot capability body" }, 403, req, ctx.config);
+      }
+      const decoded = new TextDecoder("utf-8", { fatal: true }).decode(body);
       const { desktopBadgeStore } = await import("../../update/desktop-badge");
       if (!desktopBadgeStore.put(JSON.parse(decoded))) {
         return jsonResponse({ error: "invalid desktop snapshot" }, 400, req, ctx.config);

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

@@ -26,7 +26,7 @@ import { selectEagerPath } from "../../lib/bun-stream-caps";
 import { reportedBunRuntimeSource } from "../../lib/bun-runtime";
 import { getActiveTurnCount, isDraining } from "../lifecycle";
 import { getActiveMemoryWatchdog, observedMemoryCounter } from "../memory-watchdog";
-import { responseStateMetrics } from "../../responses/state";
+import { inspectResponseSpillStorage, responseStateMetrics, type ResponseSpillDirInspection } from "../../responses/state";
 import { appOwnedBytesSnapshot } from "../../lib/app-owned-memory";
 import { readWindowsReplaceRetryCounters } from "../../lib/windows-atomic-replace";
 import {
@@ -48,6 +48,18 @@ import type { ManagementContext } from "./context";
 import { acceptSystemRestart } from "./system-restart";
 
 const ENDPOINT_SAMPLE_LIMIT = 60;
+// The spill report reads the snapshot and walks the spill directory synchronously,
+// so a polled memory endpoint reuses one result per window instead of rescanning.
+const RESPONSE_SPILL_REPORT_TTL_MS = 30_000;
+let responseSpillReport: { at: number; value: ResponseSpillDirInspection } | null = null;
+
+function cachedResponseSpillReport(): ResponseSpillDirInspection {
+  const now = Date.now();
+  if (!responseSpillReport || now - responseSpillReport.at >= RESPONSE_SPILL_REPORT_TTL_MS) {
+    responseSpillReport = { at: now, value: inspectResponseSpillStorage() };
+  }
+  return responseSpillReport.value;
+}
 
 export async function handleSystemRoutes(ctx: ManagementContext): Promise<Response | null> {
   const { req, url, config, version } = ctx;
@@ -121,6 +133,11 @@ export async function handleSystemRoutes(ctx: ManagementContext): Promise<Respon
 	      observedMetric: observed.observedMetric,
 	      jscHeap,
       responseState: responseStateMetrics(),
+      // Dry-run spill-directory counters: owned vs orphan-candidate bytes, same
+      // predicate the startup reclaim uses. Sibling of responseState, not a field
+      // in it — that block's key count is pinned. Still scalar-only. Cached for
+      // RESPONSE_SPILL_REPORT_TTL_MS.
+      responseSpill: cachedResponseSpillReport(),
       appOwnedBytes: appOwnedBytesSnapshot(),
       inspectionCounters: getInspectionCounters(),
       streamMode,