# 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.