diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md
index 5a5b32fefe5..8257fb7a146 100644
--- a/content/manuals/ai/sandboxes/configuration/environment-files.md
+++ b/content/manuals/ai/sandboxes/configuration/environment-files.md
@@ -503,6 +503,25 @@ approve the plan. They remain disabled even if you cancel the plan or restart
 the daemon. To enable them again, run `sbx env run` without the flag and approve
 the plan. Credential `command` sources still run when their secrets are needed.
 
+## Recover after losing environment state
+
+If `sbx env run` reports that a local sandbox "agrees with everything this
+environment declares" but "nothing was done", the sandbox still exists, but
+`sbx` cannot verify that it belongs to this environment. This can happen after
+an upgrade or state reset loses the environment's records.
+
+To keep using that sandbox without deleting and recreating it, run
+`sbx env run` in an interactive terminal with the same environment file paths
+and sandbox name. The command asks whether to adopt the sandbox. Confirm only
+if this is the sandbox you want the environment to manage, then review and
+approve the environment plan. Later runs recognize that sandbox, and
+`sbx env rm` can remove it.
+
+For an automated run that fails with this error, complete this recovery
+interactively before retrying the automation. `--force` approves the plan but
+doesn't confirm adoption. Only `sbx env run` offers adoption, and only when the
+sandbox matches the environment's declarations.
+
 ## Update an environment
 
 For an existing sandbox, `sbx env run` applies updated `env` values to the new