fix(gateway): address runtime config review feedback

Signed-off-by: Taylor Mutch <taylormutch@gmail.com>

Author: TaylorMutch

crates/openshell-server/src/grpc/policy.rs

@@ -1492,6 +1492,15 @@ async fn handle_update_config_inner(
     if req.global {
         let _settings_guard = state.settings_mutex.lock().await;
 
+        // Check this before dispatching the global mutation. Keep the check
+        // under settings_mutex so a runtime-file reload cannot change key
+        // ownership between this check and the stored-settings write.
+        if has_setting && state.runtime_settings.is_managed_key(key) {
+            return Err(Status::failed_precondition(format!(
+                "setting '{key}' is managed by the gateway runtime config file; update that file instead"
+            )));
+        }
+
         if has_merge_ops {
             return Err(Status::invalid_argument(
                 "merge_operations are not supported for global policy updates",
@@ -1607,12 +1616,6 @@ async fn handle_update_config_inner(
         if key != POLICY_SETTING_KEY {
             validate_registered_setting_key(key)?;
         }
-        if state.runtime_settings.is_managed_key(key) {
-            return Err(Status::failed_precondition(format!(
-                "setting '{key}' is managed by the gateway runtime config file; update that file instead"
-            )));
-        }
-
         let mut global_settings = load_global_settings(state.store.as_ref()).await?;
         let changed = if req.delete_setting {
             let removed = global_settings.settings.remove(key).is_some();
@@ -9283,7 +9286,6 @@ mod tests {
         );
     }
 
-    #[cfg(feature = "dev-settings")]
     #[test]
     fn merge_effective_settings_global_overrides_sandbox_key() {
         let global = StoredSettings {

docs/reference/gateway-config.mdx

@@ -18,6 +18,13 @@ Startup configuration is distinct from runtime settings such as `providers_v2_en
 Gateway CLI flag  >  gateway OPENSHELL_* env var  >  TOML file  >  built-in default
 ```
 
+This precedence applies only to startup configuration, including the
+`runtime_config_path` that selects the second file. Runtime setting keys are not
+exposed as gateway process flags or `OPENSHELL_*` environment variables. For a
+key present in the runtime settings file, that file is authoritative and the
+gateway rejects global API or CLI writes. A key omitted from the runtime file
+uses its stored global value and remains mutable through `openshell settings`.
+
 `database_url` is env-only. The loader rejects it when it appears in the file. When `OPENSHELL_DB_URL` is unset, the gateway stores its SQLite database under `$XDG_STATE_HOME/openshell/gateway/openshell.db`.
 
 ## Package-Managed Locations