fix: make sandbox resume state-aware

[aivong-openhands]

HUMAN:

Not yet tested by a human.

• A human has tested these changes.

AGENT:

Implemented and validated by OpenHands. This PR was created by an AI agent (OpenHands) on behalf of the user.

---

Why

Repeated resume requests currently perform sandbox-limit cleanup and Runtime API resume calls before resolving the target state. Active or transitioning runtimes can therefore trigger expensive work, key churn, and Runtime API conflicts that are flattened into application 404 responses.

Summary

• Resolve sandbox state before cleanup or resume side effects, with idempotent active-state outcomes and distinct missing, conflict, and upstream-failure semantics.
• Preserve structured Runtime API conflicts, exclude the target from cleanup races, and durably invalidate/reconcile rotated session keys without exposing them.
• Document 404/409/502 route outcomes and add state, race, security, backend, and route coverage.

Issue Number

Closes #245

How to Test

poetry run pytest -q tests/unit/app_server/test_remote_sandbox_service.py tests/unit/app_server/test_sandbox_service.py tests/unit/app_server/test_sandbox_resume_router.py tests/unit/app_server/test_docker_sandbox_service.py tests/unit/app_server/test_process_sandbox_service.py
PYTHONPATH=enterprise poetry run pytest -q tests/unit/app_server
poetry run pre-commit run --config ./dev_config/python/.pre-commit-config.yaml --show-diff-on-failure

Validated locally:

• 256 focused sandbox tests passed.
• 1,675 app-server unit tests passed.
• All configured pre-commit hooks, including Ruff and mypy, passed.

Video/Screenshots

Not applicable; this is an application API and service behavior change.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

STARTING and RUNNING are safe no-op outcomes: no resume request is sent and no session key is returned or rotated. PAUSED and ERROR perform a real resume with enforced key rotation. Missing runtimes remain 404, state conflicts remain 409, and upstream failures use 502.

@aivong-openhands can click here to continue refining the PR

---

Enterprise server image for this PR:

ghcr.io/openhands/enterprise-server:sha-7dc240f

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
openhands/app_server/sandbox
docker_sandbox_service.py					516, 520-565
process_sandbox_service.py					358, 362-379
remote_sandbox_service.py					86, 90-96, 100-105, 109, 574, 579-581, 588-594, 602-633, 642-715, 950, 962-973
sandbox_router.py					90, 109-111
sandbox_service.py					317, 334-342
Project Total

This report was generated by python-coverage-comment-action