@bitkyc08/opencodex 2.63.0 → 2.64.0-preview.20260923

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

@@ -47,6 +47,14 @@ import { fetchQoderModels } from "../../adapters/qoder/live-models";
 import { resolveQoderProfile } from "../../adapters/qoder/profiles";
 import { parseAntigravityAvailableModels } from "../../providers/antigravity-models";
 import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
+import {
+  applyProviderCompatPatchFields,
+  carryProviderCompatFields,
+  providerCompatFieldConfigError,
+  providerOverwriteKeepsDestination,
+  sampleProviderOverwrite,
+} from "./provider-overwrite-carry";
+import { shadowInterceptProviderDependency } from "./shadow-call-validation";
 import { deriveProviderPresets, providerConfigSeed } from "../../providers/derive";
 import { initializeProviderModelSelection } from "../../providers/initial-model-selection";
 import { effectiveGoogleMode, providerCodexAccountMode, providerMatchesRegistryTransport } from "../../providers/registry";
@@ -111,7 +119,7 @@ import {
   LOCAL_PROVIDER_RELOAD_NAME_HEADER,
   LOCAL_PROVIDER_RELOAD_PATH,
 } from "../../lib/local-provider-reload-contract";
-import { refreshUserCostOverlays } from "../../usage/user-cost-overlays";
+import { refreshConfigDerivedRegistries } from "../../config/derived-registries";
 import { redactSecretString } from "../../lib/redact";
 import {
   XAI_RESPONSES_OPT_IN_MODELS,
@@ -742,6 +750,10 @@ function applyProviderPatchFields(
     }
     touched = true;
   }
+  // The reasoning-replay lists, foldDeveloperRoleToSystem and reasoningWireFormat (#5563).
+  const compat = applyProviderCompatPatchFields(rawBody, next);
+  if ("error" in compat) return { error: compat.error };
+  if (compat.touched) touched = true;
 
   // headers is the one object-valued field in the mask. PATCH semantics merge it
   // shallowly into the existing block so a single fingerprint header can be added
@@ -1003,7 +1015,7 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
     reconcileLiveStateStores();
     // The complete disk snapshot owns display overlays, including providers that this
     // live routing instance deliberately does not adopt.
-    refreshUserCostOverlays(currentDiskConfig);
+    refreshConfigDerivedRegistries(currentDiskConfig);
     clearGatherRoutedModelsInflight();
     (deps.clearProviderQuotaCache ?? clearProviderQuotaCache)();
     clearAccountQuotaCache(name);
@@ -1105,7 +1117,7 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
 
     adoptProviderEditorCandidate(config, outcome.value.config);
     reconcileLiveStateStores();
-    refreshUserCostOverlays(outcome.value.config);
+    refreshConfigDerivedRegistries(outcome.value.config);
     clearGatherRoutedModelsInflight();
     (deps.clearProviderQuotaCache ?? clearProviderQuotaCache)();
     clearAccountQuotaCache();
@@ -1140,7 +1152,8 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
     const pinError = applyProviderPinFields(transportCandidate as unknown as OcxProviderConfig, body.provider, existing);
     if (pinError) return jsonResponse({ error: pinError }, 400);
     const providerError = providerManagementConfigError(name, transportCandidate)
-      ?? providerEmptyToolOutputConfigError(name, transportCandidate);
+      ?? providerEmptyToolOutputConfigError(name, transportCandidate)
+      ?? providerCompatFieldConfigError(body.provider as Record<string, unknown>);
     if (providerError) return jsonResponse({ error: providerError }, 400);
     const rawProvider = body.provider as Record<string, unknown>;
     if (rawProvider.upstreamWebsocket !== undefined && typeof rawProvider.upstreamWebsocket !== "boolean") {
@@ -1195,12 +1208,17 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
     // from "the registry supplied it" either. Without this sample, an unrelated edit that
     // omits the key resurrects the registry default over an operator's explicit `false`.
     const submittedAnnotateEmptyToolOutputs = Object.hasOwn(prov, "annotateEmptyToolOutputs");
+    // And for the compatibility settings, several of which enrichment fills from the registry
+    // seed (#5563); the sample also records whether the request named an auth mode.
+    const overwriteSample = sampleProviderOverwrite(prov);
     enrichProviderFromCatalog(name, prov);
     const { saveConfigPreservingClaudeCode: save } = await import("../../config");
     // Overwriting an existing provider must not drop its multi-key pool: carry it over, then
-    // let the (possibly new) apiKey join the pool as the active entry.
+    // let the (possibly new) apiKey join the pool as the active entry. Only while the provider
+    // keeps its destination: those keys were issued for the previous upstream.
     const existingPool = config.providers[name]?.apiKeyPool;
-    if (existingPool && !prov.apiKeyPool) prov.apiKeyPool = existingPool;
+    if (existingPool && !prov.apiKeyPool
+      && providerOverwriteKeepsDestination(prov, config.providers[name], overwriteSample)) prov.apiKeyPool = existingPool;
     // The same rule applies to user-configured price overlays: the dashboard's
     // add/edit form does not send modelCosts, so an overwrite must not silently
     // erase hand-edited per-model prices from Logs/Usage estimates.
@@ -1259,6 +1277,10 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
     if (!submittedUpstreamWebsocket && existing?.upstreamWebsocket !== undefined) {
       prov.upstreamWebsocket = existing.upstreamWebsocket;
     }
+    // The form sends none of the compatibility settings either (#5563). Read the live row rather
+    // than `existing`, like the alias overlays below: a PATCH that saved one of them while DNS
+    // validation awaited must not be undone. Nothing is carried to a new destination.
+    carryProviderCompatFields(prov, config.providers[name], overwriteSample);
     if (existing?.modelContextWindows) {
       // When the client did send a map, its keys win and the user's other keys survive. When
       // it did not, the stored value is the user's map alone: merging the registry seed in
@@ -1475,6 +1497,10 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
     // mask onto the newest provider under the mutation lock right before saving, so two
     // concurrent PATCHes updating different fields/headers both survive instead of the
     // later save clobbering the earlier snapshot.
+    // Read before the save: once the provider is disabled the target no longer resolves (#5618).
+    const shadowDependency = rawBody.disabled === true && config.providers[name]!.disabled !== true
+      ? shadowInterceptProviderDependency(config, name)
+      : null;
     let replayError: string | undefined;
     withConfigMutationLockSync(() => {
       const replay = applyProviderPatchFields(name, config.providers[name]!, rawBody, keys, config);
@@ -1540,6 +1566,7 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       name,
       disabled: config.providers[name]!.disabled === true,
       hasApiKey: !!config.providers[name]!.apiKey,
+      ...(shadowDependency ? { dependentShadowIntercept: shadowDependency } : {}),
       ...(name === "xai"
         ? { xaiResponsesOptInState: xaiResponsesOptInState(config.providers[name]!) }
         : {}),
@@ -1753,6 +1780,8 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       }, 409);
     }
     const { saveConfigPreservingClaudeCode: save } = await import("../../config");
+    // Deleting still succeeds; the response names the shadow-call target left without a provider.
+    const shadowDependency = shadowInterceptProviderDependency(config, name);
     if (fallbackDefault) config.defaultProvider = fallbackDefault;
     delete config.providers[name];
     const { dropProviderCustomModels } = await import("../../providers/provider-id-rewrite");
@@ -1768,6 +1797,7 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       success: true,
       ...(fallbackDefault ? { defaultProvider: fallbackDefault } : {}),
       ...(droppedCustomModels > 0 ? { droppedCustomModels } : {}),
+      ...(shadowDependency ? { dependentShadowIntercept: shadowDependency } : {}),
       catalogRefresh,
     });
   }

package/src/server/management/remote-workspace-routes.ts

@@ -10,9 +10,9 @@ function response(body: unknown, status = 200): Response {
 }
 
 function sessionOnly(ctx: ManagementContext): Response | null {
-  return ctx.principal === "gui-session"
+  return ctx.principal === "gui-session" && ctx.sessionControl?.isPaired(ctx.req, ctx.config) === true
     ? null
-    : response({ error: "A dashboard session is required for Remote Workspace changes." }, 403);
+    : response({ error: "A paired dashboard session is required for Remote Workspace changes." }, 403);
 }
 
 async function jsonObject(req: Request): Promise<Record<string, unknown>> {

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

@@ -148,6 +148,8 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "POST", path: "/api/grok/apply", module: "server/management/agent-settings-routes", mutates: true },
   { method: "GET", path: "/api/grok/reset-coupons", module: "server/management/grok-coupon-routes", mutates: false },
   { method: "POST", path: "/api/grok/reset-coupons/consume", module: "server/management/grok-coupon-routes", mutates: true },
+  { method: "GET", path: "/api/anthropic/reset-grants", module: "server/management/anthropic-reset-grant-routes", mutates: false, exempt: { reason: "deferred-verb", why: "Reading Claude reset grants has no CLI verb yet; the dashboard ticket badge is the only reader in this unit.", owner: "260923_claude_reset_grants wp1", ownerDoc: "devlog/_plan/260923_claude_reset_grants/010_plan.md" } },
+  { method: "POST", path: "/api/anthropic/reset-grants/consume", module: "server/management/anthropic-reset-grant-routes", mutates: true, exempt: { reason: "session-only", why: "Spending a Claude reset grant requires the gui-session principal (anthropic-reset-grant-routes.ts handleConsume); the admin token is refused." } },
   { method: "PUT", path: "/api/claude-code", module: "server/management/agent-settings-routes", mutates: true },
   { method: "PUT", path: "/api/claude-desktop", module: "server/management/agent-settings-routes", mutates: true },
   { method: "PUT", path: "/api/codex-auth/features/default-mode-request-user-input", module: "server/management/agent-settings-routes", mutates: true },

package/src/server/management/shadow-call-validation.ts

@@ -13,6 +13,11 @@ export function shadowCallTargetError(config: OcxConfig, targetModel: string | u
   } catch {
     return "model must resolve to a configured provider";
   }
+  // A qualified target that only the router's last-resort default-provider fallback accepts names
+  // nothing configured; saving it would leave the same dead target the request path refuses (#5618).
+  if (target.routeKind === "default-provider" && targetModel.includes("/")) {
+    return "model must resolve to a configured provider";
+  }
 
   const intersectsSource = shadowSourceModels(config.shadowCallIntercept?.sourceModels).some(sourceModel => {
     let source = { providerName: OPENAI_CODEX_PROVIDER_ID, modelId: sourceModel };
@@ -27,3 +32,37 @@ export function shadowCallTargetError(config: OcxConfig, targetModel: string | u
     ? "shadow-call target must not intersect a source model"
     : null;
 }
+
+/** The shadow-call reference a provider change leaves behind, reported by disable and delete. */
+export interface ShadowInterceptDependency {
+  model: string;
+  enabled: boolean;
+}
+
+/**
+ * Whether `shadowCallIntercept.model` depends on `providerName` (#5618). Call it before the
+ * mutation. A `provider/model` or `alias/model` target naming the provider counts, and so does
+ * any other target the router currently resolves to it. Combo and routing-profile targets do not:
+ * their pickers already skip a disabled or missing member, and deleting a provider a combo uses is
+ * refused outright.
+ */
+export function shadowInterceptProviderDependency(config: OcxConfig, providerName: string): ShadowInterceptDependency | null {
+  const shadow = config.shadowCallIntercept;
+  const model = shadow?.model?.trim();
+  if (!model) return null;
+  const dependency = { model, enabled: shadow?.enabled === true };
+  const slash = model.indexOf("/");
+  if (slash > 0) {
+    const prefix = model.slice(0, slash).toLowerCase();
+    const alias = config.providers[providerName]?.alias?.trim().toLowerCase();
+    if (prefix === providerName.toLowerCase() || (alias && prefix === alias)) return dependency;
+  }
+  let target;
+  try {
+    target = routeModel(config, model);
+  } catch {
+    return null;
+  }
+  if (target.routeKind === "combo" || target.routeKind === "policy") return null;
+  return target.providerName === providerName ? dependency : null;
+}

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

@@ -23,6 +23,7 @@
  */
 import { spawn } from "node:child_process";
 import {
+  acquireTemporaryDrain,
   beginShutdownDrain,
   drainAndShutdown,
   getActiveTurnCount,
@@ -54,6 +55,7 @@ export interface ReplacementReadinessIo {
 }
 
 export interface SystemRestartIo {
+  acquireTemporaryDrain?: () => { release(): void } | null;
   drainAndShutdown?: typeof drainAndShutdown;
   /** True when a background service can actually respawn this process after exit(1). */
   isServiceViable?: () => boolean;
@@ -75,6 +77,13 @@ export interface SystemRestartIo {
   now?: () => number;
 }
 
+export interface SystemRestartAdmission {
+  /** Only the caller that created this pending restart receives its veto. */
+  onAccepted?: (veto: () => void) => void;
+  /** Recheck external authority before draining or handing off. */
+  beforeScheduledDrain?: () => boolean;
+}
+
 let restartIo: SystemRestartIo = {};
 /** Prevents double-scheduling in the 200ms window before drainAndShutdown sets draining. */
 let restartAccepted = false;
@@ -135,10 +144,21 @@ function waitForBoundedSettlement(
   });
 }
 
+/**
+ * Set when an operator-initiated shutdown (signal or management stop) begins. An automatic
+ * restart that is already draining cannot tell its own listener stop from an independent one,
+ * so it consults this instead and never hands off after the process was asked to stop.
+ */
+let explicitShutdownRequested = false;
+export function noteExplicitShutdownRequested(): void {
+  explicitShutdownRequested = true;
+}
+
 /** Test seam — reset between tests. */
 export function setSystemRestartIoForTests(io: SystemRestartIo = {}): void {
   restartIo = io;
   restartAccepted = false;
+  explicitShutdownRequested = false;
 }
 
 function resolveListenPort(): number | undefined {
@@ -297,7 +317,9 @@ async function completeDeferredParentExitHandoff(
   exitProcess: (code: number) => void,
   port: number | undefined,
   phase: "deadline" | "listener-stop fallback",
+  canHandoff: () => boolean = () => true,
 ): Promise<void> {
+  if (!canHandoff()) return;
   try {
     await (io.spawnStart ?? spawnDetachedStart)(port, false);
   } catch (err) {
@@ -317,10 +339,13 @@ async function completeDeadlineRestartHandoff(
   exitProcess: (code: number) => void,
   port: number | undefined,
   scheduleDeadline: NonNullable<SystemRestartIo["scheduleDeadline"]>,
+  canHandoff: () => boolean = () => true,
 ): Promise<void> {
+  if (!canHandoff()) return;
   const supervised = (io.isSupervisedServiceChild ?? (() => isSupervisedServiceChild(io)))();
   if (supervised) {
     // Failure-only supervisors ignore exit(0); intentional non-zero triggers respawn.
+    if (!canHandoff()) return;
     exitProcess(1);
     return;
   }
@@ -340,7 +365,7 @@ async function completeDeadlineRestartHandoff(
   }
   // The ordinary child must survive parent exit: a failed/pending socket close
   // or overdue cleanup is completed by process teardown, without a hidden mode.
-  await completeDeferredParentExitHandoff(io, exitProcess, port, "deadline");
+  await completeDeferredParentExitHandoff(io, exitProcess, port, "deadline", canHandoff);
 }
 
 /**
@@ -348,7 +373,7 @@ async function completeDeadlineRestartHandoff(
  * respawn runs on a short timer so the HTTP response can flush first.
  * Idempotent while already draining: returns the accepted shape again.
  */
-export function acceptSystemRestart(io: SystemRestartIo = restartIo): {
+export function acceptSystemRestart(io: SystemRestartIo = restartIo, admission: SystemRestartAdmission = {}): {
   accepted: true;
   alreadyDraining: boolean;
   activeTurnCount: number;
@@ -363,13 +388,50 @@ export function acceptSystemRestart(io: SystemRestartIo = restartIo): {
 
   if (!alreadyDraining) {
     restartAccepted = true;
+    const automatic = Boolean(admission.onAccepted);
+    const temporaryDrain = automatic
+      ? (io.acquireTemporaryDrain ?? (() => acquireTemporaryDrain("automatic-restart")))()
+      : null;
+    const releasePending = () => {
+      temporaryDrain?.release();
+      restartAccepted = false;
+    };
+    if (automatic && !temporaryDrain) {
+      restartAccepted = false;
+      return { accepted: true, alreadyDraining: true, activeTurnCount, drainTimeoutMs: MEMORY_DRAIN_RESTART_MS };
+    }
+    let pending = true;
+    let vetoed = false;
+    admission.onAccepted?.(() => {
+      if (!pending) return;
+      pending = false;
+      vetoed = true;
+      releasePending();
+    });
     const now = io.now ?? Date.now;
     const restartDeadlineMs = now() + MEMORY_DRAIN_RESTART_MS;
     // Reject new data-plane traffic immediately (503), before the 200ms response-flush delay.
-    if (io.beginShutdownDrain) io.beginShutdownDrain();
-    else if (io.setDraining) io.setDraining(true);
-    else beginShutdownDrain();
+    if (!automatic) {
+      if (io.beginShutdownDrain) io.beginShutdownDrain();
+      else if (io.setDraining) io.setDraining(true);
+      else beginShutdownDrain();
+    }
     schedule(async () => {
+      if (vetoed) return;
+      pending = false;
+      const canHandoff = () => {
+        // Only admission-bound (automatic) restarts yield to an explicit stop; manual restart
+        // requests keep their existing semantics.
+        if (admission.onAccepted && explicitShutdownRequested) return false;
+        try { return admission.beforeScheduledDrain?.() ?? true; }
+        catch { return false; } // Unknown ownership is not authority to restart.
+      };
+      if (!canHandoff()) { releasePending(); return; }
+      if (automatic) {
+        if (io.beginShutdownDrain) io.beginShutdownDrain();
+        else if (!io.setDraining) beginShutdownDrain();
+        temporaryDrain?.release();
+      }
       // Preserve the live binding before drainAndShutdown (or its deadline race)
       // closes the listener and makes both the server ref and runtime metadata stale.
       const restartPort = (io.listenPort ?? resolveListenPort)();
@@ -381,10 +443,11 @@ export function acceptSystemRestart(io: SystemRestartIo = restartIo): {
         return () => clearTimeout(timer);
       });
       const drainOutcome = await waitForRestartDrain(drainPromise, restartDeadlineMs, now, scheduleDeadline);
+      if (!canHandoff()) return;
       const exitProcess = io.exitProcess ?? ((code: number) => { process.exit(code); });
       if (drainOutcome === "deadline") {
         console.warn("Drain-and-restart deadline expired; forcing terminal restart handoff");
-        await completeDeadlineRestartHandoff(io, exitProcess, restartPort, scheduleDeadline);
+        await completeDeadlineRestartHandoff(io, exitProcess, restartPort, scheduleDeadline, canHandoff);
         return;
       }
       if (drainOutcome === "failed" || drainOutcome === "rejected") {
@@ -395,6 +458,7 @@ export function acceptSystemRestart(io: SystemRestartIo = restartIo): {
       const supervised = (io.isSupervisedServiceChild ?? (() => isSupervisedServiceChild(io)))();
       if (supervised) {
         // Failure-only supervisors ignore exit(0); intentional non-zero triggers respawn.
+        if (!canHandoff()) return;
         (io.exitProcess ?? ((code: number) => { process.exit(code); }))(1);
         return;
       }
@@ -407,10 +471,12 @@ export function acceptSystemRestart(io: SystemRestartIo = restartIo): {
           exitProcess,
           restartPort,
           "listener-stop fallback",
+          canHandoff,
         );
         return;
       }
       try {
+        if (!canHandoff()) return;
         // A rejected drain has uncertain cleanup ownership, so it uses the same
         // parent-exit handoff as a deadline. Only a fully completed drain waits
         // for replacement health in the old process.

package/src/server/management-api.ts

@@ -50,6 +50,7 @@ import {
 import type { OcxClaudeCodeConfig, OcxClaudeDesktopProfile, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../types";
 import type { DesktopProfileModel } from "../claude/desktop-profile";
 import { drainAndShutdown } from "./lifecycle";
+import { noteExplicitShutdownRequested } from "./management/system-restart";
 import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "./request-log";
 import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../usage/cost";
 import type { PersistedUsageAttempt } from "../usage/log";
@@ -159,6 +160,12 @@ async function handleGrokCouponRoutesOnDemand(ctx: ManagementContext): Promise<R
   return handleGrokCouponRoutes(ctx);
 }
 
+async function handleAnthropicResetGrantRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
+  if (!pathInManagementNamespace(ctx.url.pathname, "/api/anthropic/reset-grants", true)) return null;
+  const { handleAnthropicResetGrantRoutes } = await import("./management/anthropic-reset-grant-routes");
+  return handleAnthropicResetGrantRoutes(ctx);
+}
+
 async function handleRemoteWorkspaceRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
   if (!pathInManagementNamespace(ctx.url.pathname, "/api/remote-workspace")) return null;
   if (!remoteWorkspaceEnabled(ctx.config)) {
@@ -166,8 +173,11 @@ async function handleRemoteWorkspaceRoutesOnDemand(ctx: ManagementContext): Prom
       status: ctx.req.method === "GET" ? 200 : 404, headers: { "cache-control": "no-store" },
     });
   }
-  if (ctx.req.method !== "GET" && ctx.principal !== "gui-session") {
-    return Response.json({ error: "A dashboard session is required for Remote Workspace changes." }, { status: 403 });
+  if (ctx.req.method !== "GET" && (
+    ctx.principal !== "gui-session"
+    || ctx.sessionControl?.isPaired(ctx.req, ctx.config) !== true
+  )) {
+    return Response.json({ error: "A paired dashboard session is required for Remote Workspace changes." }, { status: 403 });
   }
   const { handleRemoteWorkspaceRoutes } = await import("./management/remote-workspace-routes");
   return handleRemoteWorkspaceRoutes(ctx);
@@ -274,6 +284,7 @@ export async function handleManagementAPI(
     ??     (await handleQuotaResetRoutesOnDemand(ctx))
     ??     (await handleWorkflowBudgetRoutesOnDemand(ctx))
     ??     (await handleGrokCouponRoutesOnDemand(ctx))
+    ??     (await handleAnthropicResetGrantRoutesOnDemand(ctx))
     ??     handleMetricsRoutes(ctx)
     ??     (await handleRoutingAnalyticsRoutes(ctx))
     ??     (await handleRoutingProfileRoutesOnDemand(ctx))
@@ -395,6 +406,9 @@ export async function handleManagementAPI(
     // syncCleanup skips this when OCX_SERVICE is set (so a crash/respawn keeps the fence),
     // which is exactly why an intentional stop has to do it here — unless the caller is
     // `ocx stop`, which does it itself once the proxy is proven down.
+    // Mark the stop before the first await after acceptance, so an automatic restart draining
+    // concurrently cannot reach its handoff while teardown is still pending.
+    noteExplicitShutdownRequested();
     const teardown = await performStopTeardown(url, { ownsReceipt: deferralMatchesReceipt });
     setTimeout(async () => {
       let shutdownSucceeded = false;

package/src/server/management-auth.ts

@@ -1,4 +1,13 @@
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import {
+  LOCAL_ASIDE_SYNC_CAPABILITY_HEADER,
+  LOCAL_ASIDE_SYNC_EXPECTED_PID_HEADER,
+  LOCAL_ASIDE_SYNC_EXPIRES_AT_HEADER,
+  LOCAL_ASIDE_SYNC_NONCE_HEADER,
+  LOCAL_ASIDE_SYNC_PATH,
+  parseExpectedLocalAsideSyncPid,
+  verifyLocalAsideSyncCapability,
+} from "../lib/local-aside-sync-contract";
 import {
   chmodSync,
   closeSync,
@@ -70,6 +79,8 @@ const admittedLocalReadRequests = new WeakSet<Request>();
 const LOCAL_PROVIDER_RELOAD_REPLAY_LIMIT = 256;
 const consumedLocalProviderReloadCapabilities = new Map<string, number>();
 const admittedLocalProviderReloadRequests = new WeakSet<Request>();
+const consumedLocalAsideSyncCapabilities = new Map<string, number>();
+const admittedLocalAsideSyncRequests = new WeakSet<Request>();
 const GUI_PAIR_REPLAY_LIMIT = 256;
 const consumedGuiPairCapabilities = new Map<string, number>();
 const admittedGuiPairRequests = new WeakSet<Request>();
@@ -253,23 +264,35 @@ export interface ManagementSessionControl {
   revokeCurrent(req: Request): boolean;
   /** Revalidate a long-lived request against current authority, without cached admission or renewal. */
   isCurrent(req: Request, config: OcxConfig): boolean;
+  /** Prove that the current browser session came from the operator-mediated pairing flow. */
+  isPaired(req: Request, config: OcxConfig): boolean;
 }
 
 export function createManagementSessionControl(state: ManagementAuthState): ManagementSessionControl {
+  function currentSession(req: Request, config: OcxConfig): GuiSessionRecord | null {
+    if (!state.available) return null;
+    const adminToken = state.token;
+    const credential = requestManagementCredential(req);
+    if (!credential || equalSecret(credential, adminToken)) return null;
+    const session = state.sessions.get(credential);
+    if (!session) return null;
+    // Reuse the full origin/expiry/CSRF predicate against the current record, but
+    // isolate its sliding-expiry mutation: authority checks are not browser activity.
+    return authorizeGuiSessionRequest(req, config, {
+      sessions: new Map([[credential, { ...session }]]),
+      pairingGrants: state.pairingGrants,
+    }).ok ? session : null;
+  }
   return {
     isCurrent(req: Request, config: OcxConfig): boolean {
       if (!state.available) return false;
       const credential = requestManagementCredential(req);
       if (!credential) return false;
       if (equalSecret(credential, state.token)) return true;
-      const session = state.sessions.get(credential);
-      if (!session) return false;
-      // Reuse the full origin/expiry/CSRF predicate against the current record, but
-      // isolate its sliding-expiry mutation: SSE heartbeats are not browser activity.
-      return authorizeGuiSessionRequest(req, config, {
-        sessions: new Map([[credential, { ...session }]]),
-        pairingGrants: state.pairingGrants,
-      }).ok;
+      return currentSession(req, config) !== null;
+    },
+    isPaired(req: Request, config: OcxConfig): boolean {
+      return currentSession(req, config)?.issuance === "pairing";
     },
     revokeCurrent(req: Request): boolean {
       if (!state.available) return false;
@@ -302,6 +325,7 @@ export type ManagementPrincipal =
   | "gui-pair-capability"
   | "local-read-capability"
   | "local-provider-reload-capability"
+  | "local-aside-sync-capability"
   | "system-restart-capability";
 
 export interface LocalManagementAuthContext {
@@ -432,6 +456,25 @@ function hasLocalProviderReloadCapability(
   return true;
 }
 
+function hasLocalAsideSyncCapability(req: Request, local: LocalManagementAuthContext | undefined): boolean {
+  if (admittedLocalAsideSyncRequests.has(req)) return true;
+  if (!local || req.method !== "POST") return false;
+  let url: URL;
+  try { url = new URL(req.url); } catch { return false; }
+  if (url.pathname !== LOCAL_ASIDE_SYNC_PATH || url.search !== "") return false;
+  if (parseExpectedLocalAsideSyncPid(req.headers.get(LOCAL_ASIDE_SYNC_EXPECTED_PID_HEADER)) !== local.pid) return false;
+  const expiresAt = Number(req.headers.get(LOCAL_ASIDE_SYNC_EXPIRES_AT_HEADER));
+  if (!Number.isSafeInteger(expiresAt)) return false;
+  const capability = req.headers.get(LOCAL_ASIDE_SYNC_CAPABILITY_HEADER);
+  const now = Date.now();
+  if (!verifyLocalAsideSyncCapability(local.attestationSecret, req.headers.get(LOCAL_ASIDE_SYNC_NONCE_HEADER), req.method, url.pathname, local.pid, local.port, expiresAt, capability, now)) return false;
+  for (const [used, until] of consumedLocalAsideSyncCapabilities) if (until <= now) consumedLocalAsideSyncCapabilities.delete(used);
+  if (!capability || consumedLocalAsideSyncCapabilities.has(capability) || consumedLocalAsideSyncCapabilities.size >= 256) return false;
+  consumedLocalAsideSyncCapabilities.set(capability, expiresAt);
+  admittedLocalAsideSyncRequests.add(req);
+  return true;
+}
+
 function hasGuiPairCapability(
   req: Request,
   local: LocalManagementAuthContext | undefined,
@@ -505,6 +548,7 @@ function resolveManagementAdmission(
   if (cached) return cached;
   let principal: ManagementPrincipal | null = null;
   if (hasSystemRestartCapability(req, local)) principal = "system-restart-capability";
+  else if (hasLocalAsideSyncCapability(req, local)) principal = "local-aside-sync-capability";
   else if (hasLocalProviderReloadCapability(req, local)) principal = "local-provider-reload-capability";
   else if (hasLocalReadCapability(req, local)) principal = "local-read-capability";
   else if (hasGuiPairCapability(req, local)) principal = "gui-pair-capability";