fix(todos): hydrate cold-load state from session snapshot

[v2psv]

Summary

This fixes cold-load/reload behavior for the existing Todos panel.

• Adds api/todo_state.py to derive a compact todo_state snapshot from the full settled session transcript.
• Attaches todo_state to /api/session?messages=1 responses for both WebUI sessions and CLI-backed sessions.
• Updates the frontend to prefer session.todo_state when available, while keeping the old reverse-scan over raw messages as a fallback for old servers / upgrade windows.
• Treats an explicit empty todos: [] snapshot as valid current state, so a cleared task list no longer falls through to an older non-empty todo write.

Why this fix

The Todos panel already exists and already tries to reconstruct todo state from tool messages. The bug is that reload/session reopen can display stale or missing state when:

1. the latest todo tool result is outside the initial msg_limit window, or
2. the latest todo write explicitly clears the list (todos: []), which the legacy frontend treated as "keep scanning" and could replace with an older non-empty list.

This PR only makes the existing panel hydrate from the server's authoritative settled transcript.

Test plan

Ran locally with the project venv:

/usr/local/lib/hermes-agent/venv/bin/python -m pytest \
  tests/test_todo_state.py \
  tests/test_session_todo_state_route.py \
  tests/test_todo_panel_cold_load_static.py \
  tests/test_regressions.py::test_refresh_handler_does_not_drop_tool_messages_needed_by_todos \
  -q

Result:

12 passed, 1 warning in 2.14s

Additional gates:

/usr/local/lib/hermes-agent/venv/bin/python scripts/ruff_lint.py --diff origin/master
node --check static/panels.js
node --check static/sessions.js
git diff --check

Result:

ruff_lint: no new violations on added/modified lines. OK.
node --check: passed
git diff --check: passed

[nesquena-hermes]

Pulled this into a worktree and read api/todo_state.py, the two routes.py hookpoints, and the panels.js rewrite against origin/master. This is a clean fix for a real cold-load gap, and I checked the agent-side contract it claims to mirror — it matches.

Cross-repo contract check

The module docstring says it mirrors run_agent.AIAgent._hydrate_todo_store. Confirmed against the agent source at run_agent.py:2670:

for msg in reversed(history):
    if msg.get("role") != "tool": continue
    content = msg.get("content", "")
    if '"todos"' not in content: continue
    data = json.loads(content)
    if "todos" in data and isinstance(data["todos"], list):
        last_todo_response = data["todos"]; break

derive_todo_state() walks newest-first, gates on role == "tool", the same '"todos"' not in content fast-path, and isinstance(todos, list) (todo_state.py:31). So the WebUI sidecar and the agent's in-memory hydration will agree on which write is authoritative. Good — this is the right layer to fix it on, and it stays consistent with the agent rather than inventing a parallel heuristic.

One behavior divergence worth a comment (not a blocker)

The backend treats an explicit empty todos: [] as a valid current snapshot (todo_state.py:31 accepts any list), which is the whole point of the cold-load fix. But the legacy frontend fallback still requires non-empty:

// static/panels.js:2691
if (d && Array.isArray(d.todos) && d.todos.length) return d.todos;

So during an upgrade window where the server hasn't been restarted yet (no todo_state sidecar), a cleared list still falls through to an older non-empty write — the exact bug you fixed, just on the fallback path. Since loadTodos() (panels.js:2656) prefers sessionTodoState whenever Array.isArray(sessionTodoState.todos) is true, the new path correctly handles empty, so this only bites old-server sessions. Acceptable to leave as-is, but worth a one-line comment in _legacyTodosFromMessages noting the divergence is intentional.

Redaction coverage

Nice catch wiring todo_state into redact_session_data (helpers.py:390) — todo content is free text and can carry pasted secrets, so the new test_redact_session_data_todo_state_sidecar is the right guard. The structural AST test in test_session_todo_state_route.py asserting both (raw, _all_msgs) and (sess, msgs) call sites is a smart way to lock in that both the WebUI and CLI-backed branches stay wired.

Verification suggestion

The route is hooked behind if load_messages and _all_msgs: (routes.py:4722), so it correctly uses the full merged transcript, not the truncated msg_limit display window — that's what makes it survive refresh when the latest todo write is outside the window. One manual check worth adding to the PR description: load a session whose only todo write is a clear/empty result that sits before the msg_limit cutoff, refresh, and confirm the panel shows "no active todos" rather than a stale list. CI is green across the matrix; LGTM pending that spot-check.

[v2psv]

@nesquena-hermes Thanks — this matches my read as well.

Spot-check for the empty-list / msg_limit case:

• Server side: I built a synthetic transcript with an older non-empty todo write, then a newer clear write (todos: []), followed by 40 filler assistant messages so the msg_limit=30 display tail contains no todo tool messages. Calling attach_todo_state(raw, full_transcript) still derived:

todo_state = {'todos': [], 'summary': {'total': 0}, 'version': 1, 'ts': 20.0}

So the sidecar is coming from the full transcript, not the truncated display window.

• Frontend side: I also ran loadTodos() against a session with session.todo_state.todos = [] while S.session.messages still contained a stale legacy non-empty todo tool result. The panel rendered the empty state (todos_no_active) and did not render the stale task. That confirms the new session.todo_state path wins before the legacy reverse scan.

Commands/results:

server_spot_check=OK full transcript derives empty todo_state while msg_limit tail has no todo messages
frontend_spot_check=OK empty session.todo_state wins over stale legacy message fallback

On the legacy fallback divergence: agreed. I left _legacyTodosFromMessages()'s d.todos.length behavior unchanged because it is only the old-server / no-sidecar upgrade fallback. The new server sidecar path is the authoritative path and handles empty lists correctly. If you'd prefer, I can add a small inline comment there, but I avoided extra churn since the behavior is intentionally limited to the fallback path.

[nesquena-hermes]

Shipped in v0.51.212 (Release GF). Thanks @v2psv — the new api/todo_state.py sidecar hydrates the Todos panel correctly on cold load even when the latest todo result is outside the display window, honors an explicit empty list, and swallows malformed-message errors so /api/session can't break. Redaction wired through helpers.py. Verified: full suite 7278 passed, Codex SAFE (confirmed the sidecar is redacted before response and in-window behavior is unchanged), Opus APPROVE.