Simplify lazy conversation catalog invariants

[enyst]

Summary

Follow-up to #4100 and the simplification feedback in #4100 (comment).

• make the persisted conversation catalog authoritative instead of repairing it from private runtime state during reads
• remove _reconcile_active_records() and missing-record repair paths
• publish catalog records before exposing live runtimes
• update focused tests to establish the catalog/runtime invariant explicitly
• delete unloaded persisted conversations without hydrating event history, while respecting conversation leases

Validation

• uv run pre-commit run --files openhands-agent-server/openhands/agent_server/conversation_service.py tests/agent_server/test_conversation_service.py — passed
• uv run pytest -q tests/agent_server/test_conversation_service.py tests/cross/test_conversation_lease_behavior.py -x — 98 passed
• adjacent conversation router, event router/websocket, event service, plugin, and restore suites — 262 passed
• git diff --check — passed

Baseline note

tests/agent_server/test_sockets_service_getters.py::test_events_socket_uses_app_state_conversation_service currently fails because an AsyncMock reaches json.loads(). The same failure reproduces from clean merged-main commit d06ff0b3; this PR does not modify the socket implementation or that test.

This pull request was created by an AI agent (OpenHands) on behalf of the requester.

@enyst can click here to continue refining the PR

---

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.13-nodejs22-slim	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:35b60a7-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-35b60a7-python \
  ghcr.io/openhands/agent-server:35b60a7-python

All tags pushed for this build

ghcr.io/openhands/agent-server:35b60a7-golang-amd64
ghcr.io/openhands/agent-server:35b60a752872840dd4b2d6871357163ba0e4b958-golang-amd64
ghcr.io/openhands/agent-server:codex-simplify-conversation-catalog-invariants-golang-amd64
ghcr.io/openhands/agent-server:35b60a7-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:35b60a7-golang-arm64
ghcr.io/openhands/agent-server:35b60a752872840dd4b2d6871357163ba0e4b958-golang-arm64
ghcr.io/openhands/agent-server:codex-simplify-conversation-catalog-invariants-golang-arm64
ghcr.io/openhands/agent-server:35b60a7-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:35b60a7-java-amd64
ghcr.io/openhands/agent-server:35b60a752872840dd4b2d6871357163ba0e4b958-java-amd64
ghcr.io/openhands/agent-server:codex-simplify-conversation-catalog-invariants-java-amd64
ghcr.io/openhands/agent-server:35b60a7-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:35b60a7-java-arm64
ghcr.io/openhands/agent-server:35b60a752872840dd4b2d6871357163ba0e4b958-java-arm64
ghcr.io/openhands/agent-server:codex-simplify-conversation-catalog-invariants-java-arm64
ghcr.io/openhands/agent-server:35b60a7-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:35b60a7-python-amd64
ghcr.io/openhands/agent-server:35b60a752872840dd4b2d6871357163ba0e4b958-python-amd64
ghcr.io/openhands/agent-server:codex-simplify-conversation-catalog-invariants-python-amd64
ghcr.io/openhands/agent-server:35b60a7-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-amd64
ghcr.io/openhands/agent-server:35b60a7-python-arm64
ghcr.io/openhands/agent-server:35b60a752872840dd4b2d6871357163ba0e4b958-python-arm64
ghcr.io/openhands/agent-server:codex-simplify-conversation-catalog-invariants-python-arm64
ghcr.io/openhands/agent-server:35b60a7-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim-arm64
ghcr.io/openhands/agent-server:35b60a7-golang
ghcr.io/openhands/agent-server:35b60a752872840dd4b2d6871357163ba0e4b958-golang
ghcr.io/openhands/agent-server:codex-simplify-conversation-catalog-invariants-golang
ghcr.io/openhands/agent-server:35b60a7-golang_tag_1.21-bookworm
ghcr.io/openhands/agent-server:35b60a7-java
ghcr.io/openhands/agent-server:35b60a752872840dd4b2d6871357163ba0e4b958-java
ghcr.io/openhands/agent-server:codex-simplify-conversation-catalog-invariants-java
ghcr.io/openhands/agent-server:35b60a7-eclipse-temurin_tag_17-jdk
ghcr.io/openhands/agent-server:35b60a7-python
ghcr.io/openhands/agent-server:35b60a752872840dd4b2d6871357163ba0e4b958-python
ghcr.io/openhands/agent-server:codex-simplify-conversation-catalog-invariants-python
ghcr.io/openhands/agent-server:35b60a7-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-slim

About Multi-Architecture Support

• Each variant tag (e.g., 35b60a7-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., 35b60a7-python-amd64) are also available if needed

[github-actions]

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

REST API breakage checks (OpenAPI) — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-agent-server/openhands/agent_server
conversation_service.py	758	97	87%	158–159, 168, 194–195, 199–200, 205, 290–291, 294–295, 307–308, 322, 474–475, 523, 542–543, 555, 566, 578, 587, 602–605, 611–612, 621, 623, 663, 672, 699, 705, 791, 797, 802, 808, 816–817, 826–829, 838, 850, 858, 869, 872–873, 876, 913–914, 975, 1017–1019, 1021–1022, 1025–1026, 1046, 1115–1116, 1120, 1142, 1205–1207, 1210–1211, 1215–1217, 1220–1221, 1225–1227, 1230–1231, 1260, 1269, 1309, 1317–1319, 1375, 1378, 1401, 1417, 1456, 1500, 1777, 1780
TOTAL	36226	15547	57%

[enyst]

@OpenHands /codereview and post your feedback as review with smolpaws token; feel free to post inline findings if any but it's okay if not

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[smolpaws]

🟢 Good taste — The persisted catalog is now clearly authoritative, read-time repair of private runtime drift is gone, and startup publishes the catalog record before exposing the live runtime.

Focused validation at 35b60a75:

• uv run pytest -q tests/agent_server/test_conversation_service.py tests/cross/test_conversation_lease_behavior.py -x — 98 passed
• git diff --check pr-4122-base HEAD — passed

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW

The change is localized to conversation catalog/runtime lifecycle handling, adds no dependency or public API changes, and has focused coverage for persisted round trips, unloaded deletion, lease contention, waiting hydration, and record-before-runtime publication.

VERDICT:
✅ Worth merging: The core invariant is simpler and the implementation is sound.

KEY INSIGHT:
Making the persisted catalog the single authority removes hidden repair behavior and makes catalog/runtime ownership easier to reason about.

This review was generated by an OpenHands AI agent on behalf of the requester and posted through the smolpaws account.

[openhands-ai]

OpenHands encountered an error: **Failed to fetch final response from agent server: HTTP 503 error: no available server
**

See the conversation for more information.

[all-hands-bot]

[Automatic Post]: It has been a while since there was any activity on this PR. @enyst, are you still working on it? If so, please go ahead, if not then please request review, close it, or request that someone else follow up.

This comment was created by an AI agent (OpenHands) on behalf of the user.

[github-actions]

This PR is stale because it has been open for 40 days with no activity. Remove the stale label or leave a comment, otherwise it will be closed in 10 days.

[github-actions]

This PR was closed because it had no activity for 50 days. If you feel this was closed in error, and you would like to continue the PR, please resubmit or let us know.