manual_slop/conductor/tracks/test_harness_hardening_20260310/spec.md

Specification: Hook API & Test Harness Hardening

Overview

This track focuses on stabilizing the local development and testing environment by hardening the Hook API and its associated live_gui test harness. The goal is to eliminate port conflicts, ensure graceful teardowns, and standardize state serialization, laying the groundwork for a future WebSockets implementation.

Functional Requirements

• Dynamic Port Allocation:
  • The Hook Server (src/api_hooks.py) will implement a Sequential Fallback strategy for port binding.
  • It will attempt to bind to port 8999. If Address already in use is encountered, it will sequentially try ports up to 9010 until successful.
  • The successfully bound port will be written to a temporary artifact file (e.g., .mcp_port or similar) so the test harness can discover it.
• Graceful Teardown:
  • Implement a new /api/shutdown POST endpoint in the Hook API.
  • When called, this endpoint should safely signal the AppController and App to initiate a clean shutdown (joining threads, closing files) rather than relying on the OS to forcefully kill the process tree.
  • Update the live_gui fixture to call this endpoint during the finally block before resorting to taskkill as a last-resort fallback.
• State Serialization Audit:
  • Formalize the structure returned by /api/gui/state.
  • Ensure all fields defined in _gettable_fields are safely serialized using standard dataclass/dict traversal (avoiding deep Pydantic dependencies for now, keeping it lightweight but strictly typed for future WebSocket pipeline compatibility).
  • Add missing fields discovered during recent UI tracks (e.g., show_windows states).

Non-Functional Requirements

• Stability: The live_gui fixture must pass 100% of the time without port conflict errors when tests are run sequentially.
• Performance: The port scanning logic should fail fast and bind within milliseconds.

Acceptance Criteria

• A test script can successfully launch two concurrent live_gui instances, and they bind to different ports.
• Calling /api/shutdown successfully stops the GUI process and returns a 200 OK.
• The live_gui fixture uses the shutdown endpoint and the test suite passes without leaving orphaned processes.
• The state returned by /api/gui/state is fully documented and includes all relevant nested objects (like show_windows).

Out of Scope

• Implementing the WebSockets streaming logic (this track only prepares the state schema for it).
• Fixing failing simulation tests that are unrelated to the harness itself.