Skip to content

TUI Handling Internals

This doc set explains how houmao-server performs server-owned live TUI tracking. It is intentionally about the internal watch plane: discovery, polling, parsing, and tracked-state authority.

The key architectural boundary is:

  • houmao-server owns the src/houmao/server/tui/ watch-plane module: discovery, polling, parsing, host-side lifecycle, and terminal-keyed live lookup.
  • houmao.shared_tui_tracking owns tracker semantics for raw-snapshot reduction, detector/profile resolution, and tracker-owned surface / turn / last_turn.
  • The supervised child cao-server still exists for CAO-compatible control routes, but it is no longer in the parsing or live-state authority path.
  • Live tracker state is memory-primary. On restart, the server rebuilds watch authority from registration records plus current tmux liveness instead of replaying old tracker snapshots from disk.
  • The public tracked-state contract is now centered on diagnostics, foundational surface observables, current turn, and sticky last_turn, while lifecycle authority and settle timing remain internal tracker machinery.

Module Map

Public Surface Versus Internal Authority

The public Houmao-owned routes for the tracker are still terminal-keyed:

  • POST /houmao/launches/register
  • GET /houmao/terminals/{terminal_id}/state
  • GET /houmao/terminals/{terminal_id}/history

Internally, the tracker is not keyed by terminal_id. The authoritative identity is HoumaoTrackedSessionIdentity, whose primary key is tracked_session_id and whose compatibility alias set includes the terminal id. terminal_id remains the public lookup token, but route resolution goes through an alias map held by houmao-server instead of making terminal id the internal watch authority.

Reading Order

  1. tui_tracking_module.md
  2. registration_and_discovery.md
  3. probe_parse_track_pipeline.md
  4. live_state_model.md
  5. supervisor_and_lifecycle.md

Primary Source References