OpenProgram Docs

WebSocket Command Lifecycle Task Brief and Ledger#

Contract#

  • Approved design: docs/reference/design/ui/websocket-command-lifecycle.html.
  • Base commit: c1f10273.
  • Production file: openprogram/webui/server.py.
  • Test file: tests/unit/test_websocket_command_lifecycle.py.
  • Public RED cases: handler failure followed by ping on one socket; invalid JSON followed by ping; last focused connection disconnect releases legacy follow-up with None; another focused connection preserves wait and can answer; empty string remains a real answer.
  • Error/privacy: client receives a stable generic handler_error; payload and exception message are not returned; local structured log retains traceback.
  • Ownership/concurrency: dispatcher never clears action-owned reservation; only the last focused connection signals the session queue; queue removal remains owned by _web_follow_up.
  • Compatibility: unknown-action frame and normal answers unchanged; socket write failure still terminates transport; runtime QuestionRegistry unchanged.
  • Exclusions: global ask-user redesign, runtime.ask/ACP/channel protocols, send queue changes, Windows, credential store, orphan files, and other audit findings.

Full gate manifest#

pytest -q tests/unit/test_websocket_command_lifecycle.py tests/unit/test_webui_head_mirror_and_run_guard.py tests/unit/test_turn_cancellation.py tests/meta_functions/test_follow_up.py
ruff check openprogram/webui/server.py tests/unit/test_websocket_command_lifecycle.py
python -m tools.docs_site.build
python -m tools.docs_site.checklinks
git diff --check
git status --short

Ledger#

Evidence Result
Base c1f10273
Design 84fe7da9 (docs(web): define websocket command lifecycle)
RED tests/unit/test_websocket_command_lifecycle.py: 2 failed, 3 passed; handler failure closed the socket before ping, and last focused disconnect left the legacy follow-up thread waiting
GREEN Initial implementation: 5 passed; review repairs added malformed metadata, repeated disconnect/cancel, transport disconnect, and unknown-action coverage
Affected verification 67 passed; scoped Ruff passed; git diff --check passed
Specification review PASS at 4bc76c83; 63 passed plus unknown-action and transport-write probes
Quality review PASS at 781de2b1; all disclosure, repeated-wait, transport-classification, and unknown-action findings repaired
Full gate 67 passed; Ruff passed; docs 457 pages; 0 broken links; git diff --check passed
Final implementation 4bc76c83, be307d4b, 781de2b1
Last updated · 2026-08-13
PreviousStructured Output Retry Budget Task Brief and LedgerNextDesktop App Icon Flat Design