diff --git a/Cargo.lock b/Cargo.lock
index a68a2197fc..46a2348d68 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1088,7 +1088,7 @@ dependencies = [
  "futures-sink",
  "futures-util",
  "http",
- "indexmap 2.0.0",
+ "indexmap 2.2.3",
  "slab",
  "tokio",
  "tokio-util",
diff --git a/ci/prow/fcos-e2e.sh b/ci/prow/fcos-e2e.sh
index 46d5db3c7c..c3cecae165 100755
--- a/ci/prow/fcos-e2e.sh
+++ b/ci/prow/fcos-e2e.sh
@@ -9,9 +9,9 @@ ls -al /usr/bin/rpm-ostree
 rpm-ostree --version
 cd $(mktemp -d)
 cosa init https://github.com/coreos/fedora-coreos-config/
-# let's turn on opt-usrlocal-overlays in this test since CoreOS CI already
+# let's turn on stateoverlays in this test since CoreOS CI already
 # covers the off path
-echo -e '\nopt-usrlocal-overlays: true\n' >> src/config/manifest.yaml
+echo -e '\nopt-usrlocal: "stateoverlay"\n' >> src/config/manifest.yaml
 cp /cosa/component-rpms/*.rpm overrides/rpm
 # XXX: temporarily import new ostree until it makes it into FCOS
 (cd overrides/rpm && curl -L --remote-name-all https://kojipkgs.fedoraproject.org//packages/ostree/2024.2/1.fc39/x86_64/ostree-{,libs-}2024.2-1.fc39.x86_64.rpm)
diff --git a/docs/treefile.md b/docs/treefile.md
index c03819bc79..b289c1194c 100644
--- a/docs/treefile.md
+++ b/docs/treefile.md
@@ -479,9 +479,10 @@ version of `rpm-ostree`.
    names to use when substituting variables in yum repo files. The `releasever`
    variable name is invalid. Use the `releasever` key instead. The `basearch`
    name is invalid; it is filled in automatically.
- * `opt-usrlocal-overlays`: boolean, optional: Defaults to `false`.  By
-   default, `/opt` and `/usr/local` are symlinks to subdirectories in `/
-   var`. This prevents the ability to compose with packages that install in
-   those directories. If enabled, RPMs with `/opt` and `/usr/local` content
-   are allowed; client-side, both paths are writable overlay directories on.
-   Requires libostree v2023.9+.
+ * `opt-usrlocal`: enum, optional: Defaults to `var`.  There are
+   three possible behaviors:
+   - `var`: `/opt` and `/usr/local` are symlinks to subdirectories in `/var`
+     and are purely machine-local state.
+   - `root`: These are plain directories; only use this with composefs enabled!
+   - `stateoverlay`: DO NOT USE THIS ONLY FOR TESTS
+
diff --git a/rpmostree-cxxrs.cxx b/rpmostree-cxxrs.cxx
index f6930f5314..5c1df6412a 100644
--- a/rpmostree-cxxrs.cxx
+++ b/rpmostree-cxxrs.cxx
@@ -1773,7 +1773,7 @@ struct Treefile final : public ::rust::Opaque
   ::rpmostreecxx::RepoMetadataTarget get_repo_metadata_target () const noexcept;
   bool rpmdb_backend_is_target () const noexcept;
   bool should_normalize_rpmdb () const noexcept;
-  bool get_opt_usrlocal_overlays () const noexcept;
+  bool get_opt_usrlocal () const noexcept;
   ::rust::Vec< ::rust::String> get_files_remove_regex (::rust::Str package) const noexcept;
   ::rust::String get_checksum (::rpmostreecxx::OstreeRepo const &repo) const;
   ::rust::String get_ostree_ref () const noexcept;
diff --git a/tests/compose/test-state-overlays.sh b/tests/compose/test-state-overlays.sh
index a5a6bfa236..a248c3d61a 100755
--- a/tests/compose/test-state-overlays.sh
+++ b/tests/compose/test-state-overlays.sh
@@ -27,7 +27,7 @@ ln "$PWD/yumrepo.repo" config/yumrepo.repo
 treefile_append "packages" '["test-opt", "test-usr-local"]'
 
 # enable state overlays
-treefile_set "opt-usrlocal-overlays" 'True'
+treefile_set "opt-usrlocal" 'stateoverlay'
 
 runcompose
 
diff --git a/tests/kolainst/destructive/apply-live b/tests/kolainst/destructive/apply-live
index 25310aeca4..b2ed11ada3 100755
--- a/tests/kolainst/destructive/apply-live
+++ b/tests/kolainst/destructive/apply-live
@@ -27,7 +27,7 @@ cd $(mktemp -d)
 
 # apply-live is not yet compatible with state overlays
 # https://github.com/coreos/rpm-ostree/pull/4810#issuecomment-1939351259
-if jq -e '.["opt-usrlocal-overlays"]' /usr/share/rpm-ostree/treefile.json; then
+if test $(jq -r '.["opt-usrlocal"]' /usr/share/rpm-ostree/treefile.json) = "stateoverlay"; then
     echo "skip apply-live does not work currently with state overlays"
     exit 0
 fi
diff --git a/tests/kolainst/destructive/state-overlays b/tests/kolainst/destructive/state-overlays
index 2d00afa661..67c2e0eba7 100755
--- a/tests/kolainst/destructive/state-overlays
+++ b/tests/kolainst/destructive/state-overlays
@@ -31,10 +31,10 @@ case "${AUTOPKGTEST_REBOOT_MARK:-}" in
       rpm-ostree override replace https://bodhi.fedoraproject.org/updates/FEDORA-2024-6c7480dd2f
     fi
 
-    # FCOS doesn't enable opt-usrlocal-overlays yet. It's on in Prow CI though.
+    # FCOS doesn't enable opt-usrlocal = stateoverlay yet. It's on in Prow CI though.
     # Just check the treefile so we do the right thing regardless of CoreOS CI
     # or Prow.
-    if ! jq -e '.["opt-usrlocal-overlays"]' /usr/share/rpm-ostree/treefile.json; then
+    if test $(jq -r '.["opt-usrlocal"]' /usr/share/rpm-ostree/treefile.json) = null; then
       mkdir -p /etc/systemd/system/rpm-ostreed.service.d/
       cat > /etc/systemd/system/rpm-ostreed.service.d/state-overlay.conf <<EOF
 [Service]