[codex] add windows smoke test workflow

docs/install-notes-windows.md

@@ -0,0 +1,67 @@
+# Windows Install Notes
+
+## Current Validated Behavior
+
+- Validated on the ASUS machine with Ableton Live `12.3.6`.
+- `ClaudeMCP_Remote` did not become selectable when copied only into the user-level Ableton library path.
+- On this machine, Ableton discovered the script only after it was copied into:
+
+```text
+C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\ClaudeMCP_Remote
+```
+
+- After installation, the script still had to be selected manually in `Options > Preferences > Link, Tempo & MIDI`.
+- The script then logged successful startup and exposed a TCP listener on `127.0.0.1:9004`.
+
+## Recommended Install Procedure
+
+1. Close Ableton Live.
+2. Open PowerShell as Administrator if the `ProgramData` directory requires elevation.
+3. From the repo root, run:
+
+```powershell
+.\scripts\windows\deploy_control_surface.ps1
+```
+
+4. Start Ableton Live.
+5. Open `Options > Preferences > Link, Tempo & MIDI`.
+6. Pick `ClaudeMCP_Remote` in an empty `Control Surface` slot.
+7. Leave `Input` and `Output` unset unless another test explicitly requires them.
+
+## Verify Startup
+
+Check the Ableton log:
+
+```powershell
+Get-Content "$env:APPDATA\Ableton\Live 12.3.6\Preferences\Log.txt" -Tail 200
+```
+
+Expected startup lines include:
+
+- `Socket server started successfully on port 9004`
+- `ClaudeMCP Remote Script initialized (Queue-based, Thread-Safe)`
+- `Socket server listening on port 9004`
+
+## Verify Listener
+
+```powershell
+Get-NetTCPConnection -LocalPort 9004 -ErrorAction SilentlyContinue | Format-Table -AutoSize LocalAddress,LocalPort,State,OwningProcess
+```
+
+Expected result:
+
+- `127.0.0.1 9004 Listen <pid>`
+
+## Verify With Smoke Test
+
+```powershell
+.\scripts\windows\run_smoke_test.ps1
+```
+
+That wrapper runs the read-only smoke client and writes raw request/response output under `logs\`.
+
+## Operational Notes
+
+- On this machine, Windows-native runtime validation is more reliable than WSL for socket checks against Ableton.
+- Treat WSL as the editing environment and Windows PowerShell as the runtime validation environment.
+- Do not modify core Remote Script files for installation-only troubleshooting unless later evidence requires it.

docs/poc-01-session-bootstrapper.md

@@ -0,0 +1,97 @@
+# POC 01: Session Bootstrapper
+
+## Objective
+
+Establish a minimal, additive validation path that proves the `ClaudeMCP_Remote` Control Surface loads in Ableton Live, starts its localhost TCP server, and responds to at least one read-only request from an external client.
+
+## Scope
+
+- Install or verify the existing `ClaudeMCP_Remote` folder in Ableton's User Library Remote Scripts path on Windows.
+- Select `ClaudeMCP_Remote` as an Ableton Control Surface.
+- Confirm that Ableton listens on `127.0.0.1:9004`.
+- Run `scripts/poc/smoke_test_client.py` using read-only actions only.
+- Capture raw request and raw response output for review.
+
+## Non-goals
+
+- No bootstrapper logic beyond smoke validation.
+- No live-performance workflow logic.
+- No edits to `ClaudeMCP_Remote/__init__.py`.
+- No edits to `ClaudeMCP_Remote/liveapi_tools.py`.
+- No changes to the hard-coded action router.
+- No attempt to validate all advertised tools.
+
+## Inputs
+
+- Local fork checkout on the ASUS machine.
+- Ableton Live installed on Windows.
+- Existing Remote Script source under `ClaudeMCP_Remote/`.
+- Smoke client at `scripts/poc/smoke_test_client.py`.
+- Ableton log file at `%APPDATA%\Ableton\Live x.x.x\Preferences\Log.txt`.
+
+## Outputs
+
+- Evidence that Ableton loaded the Control Surface without obvious startup errors.
+- Evidence that `127.0.0.1:9004` is listening while Ableton is running.
+- Raw request and raw response output from a read-only smoke test.
+- A simple pass/fail result for this phase.
+
+## Proposed Command Sequence
+
+```powershell
+cd C:\path\to\ableton-liveapi-tools-fork
+python scripts\poc\smoke_test_client.py --host 127.0.0.1 --port 9004 --log-file logs\smoke-test-session.txt
+```
+
+Optional explicit single-action probe:
+
+```powershell
+python scripts\poc\smoke_test_client.py --action ping --log-file logs\smoke-test-ping.txt
+```
+
+Optional listener check before the client run:
+
+```powershell
+netstat -ano | findstr 9004
+```
+
+## Verification Steps
+
+1. Confirm `ClaudeMCP_Remote` is present under the Ableton User Library Remote Scripts directory.
+2. Launch Ableton Live and select `ClaudeMCP_Remote` in Preferences > Link, Tempo & MIDI > Control Surface.
+3. Open the Ableton log and confirm there is no immediate `ClaudeMCP` startup exception.
+4. Confirm a localhost listener exists on port `9004`.
+5. Run the smoke client and verify that the first action is read-only.
+6. Review the captured raw request and raw response output in the chosen log file.
+
+## Risks
+
+- Upstream install docs appear to overstate autoloading; manual Control Surface selection is likely required.
+- The protocol is inferred from repo code and examples, not from a formal spec.
+- Ableton can load the Control Surface but still fail to bind the socket if the port is already in use.
+- `get_session_info` is read-only but still depends on the main-thread queue path being healthy.
+- The Ableton log location varies by installed version string.
+
+## Pass/Fail Criteria
+
+Pass:
+
+- Ableton loads `ClaudeMCP_Remote` without obvious startup failure.
+- Port `9004` is listening on `127.0.0.1`.
+- The smoke client sends a read-only request first.
+- The smoke client receives valid JSON with `"ok": true`.
+- Raw request/response output is saved for review.
+
+Fail:
+
+- Ableton cannot load or select the Control Surface.
+- No listener appears on port `9004`.
+- The client cannot connect or times out.
+- The response is empty, malformed, or returns `"ok": false`.
+
+## Rollback Approach
+
+- Deselect `ClaudeMCP_Remote` in Ableton Preferences and switch the Control Surface slot back to `None`.
+- Remove or rename the installed `ClaudeMCP_Remote` directory from the Ableton User Library Remote Scripts path if needed.
+- Delete only the smoke-test log files created under `logs/`.
+- Leave core repo files unchanged, since this phase is additive only.

docs/poc-02-status-monitor.md

@@ -0,0 +1,153 @@
+# POC 02: Status Monitor
+
+## Objective
+
+Define a minimal, additive status-monitor layer that improves confidence in `ClaudeMCP_Remote` runtime health without modifying the core Remote Script, the 220-action router, or any live-performance behavior.
+
+## Scope
+
+- Build on the validated Windows smoke-test workflow from POC 01.
+- Focus on read-only runtime signals already exposed by the repo and the host environment.
+- Standardize how to confirm that the Control Surface loaded, the TCP server is listening, and basic session health can be queried safely.
+- Capture evidence from both Ableton logs and TCP responses for later review.
+
+## Non-goals
+
+- No edits to `ClaudeMCP_Remote/__init__.py`.
+- No edits to `ClaudeMCP_Remote/liveapi_tools.py`.
+- No changes to the static action router.
+- No event subscription or observer subsystem.
+- No attempt to stream real-time session state.
+- No live-performance automation, transport control, or write actions.
+
+## Current Known Signals
+
+From repo inspection and runtime validation, the following read-only signals already exist:
+
+- Ableton log messages emitted through `c_instance.log_message(...)`.
+- Startup log lines including:
+  - `Socket server started successfully on port 9004`
+  - `ClaudeMCP Remote Script initialized (Queue-based, Thread-Safe)`
+  - `Socket server listening on port 9004`
+  - `Client connected from ...`
+- TCP listener on `127.0.0.1:9004`.
+- Read-only TCP actions:
+  - `ping`
+  - `health_check`
+  - `get_session_info`
+
+## Proposed Monitor Surface
+
+The status monitor for this phase should be a wrapper-level workflow, not a new core feature.
+
+### Layer 1: Process and startup evidence
+
+- Confirm Ableton Live is running.
+- Confirm `ClaudeMCP_Remote` is selected as a Control Surface.
+- Confirm recent Ableton log lines show successful script startup rather than an import or bind failure.
+
+### Layer 2: Listener evidence
+
+- Confirm Windows shows `127.0.0.1:9004` in `Listen` state.
+- Record the owning process ID when available.
+
+### Layer 3: Read-only protocol evidence
+
+- Run `ping` to prove command/response flow works.
+- Run `health_check` to capture:
+  - `ok`
+  - `message`
+  - `tool_count`
+  - `ableton_version`
+  - `queue_size`
+- Run `get_session_info` to capture:
+  - playback state
+  - tempo
+  - time signature
+  - track count
+  - scene count
+  - loop values
+
+### Layer 4: Evidence capture
+
+- Save raw request and raw response payloads.
+- Save a short Ableton log extract around startup and the client connection event.
+- Keep outputs timestamped for side-by-side review across runs.
+
+## Proposed Artifacts
+
+This phase does not require core-code changes. The likely additive outputs are:
+
+- a small Windows-native wrapper script for repeated status checks
+- a status log file under `logs/`
+- a short runbook section or dedicated doc for interpreting the captured signals
+
+The current repo already includes most of the needed pieces:
+
+- `scripts/windows/run_smoke_test.ps1`
+- `scripts/poc/smoke_test_client.py`
+- `docs/smoke-test-runbook.md`
+
+## Proposed Command Sequence
+
+```powershell
+.\scripts\windows\deploy_control_surface.ps1
+```
+
+Restart Ableton Live, select `ClaudeMCP_Remote`, then run:
+
+```powershell
+.\scripts\windows\run_smoke_test.ps1
+```
+
+Optional direct checks:
+
+```powershell
+Get-NetTCPConnection -LocalPort 9004 -ErrorAction SilentlyContinue | Format-Table -AutoSize LocalAddress,LocalPort,State,OwningProcess
+Get-Content "$env:APPDATA\Ableton\Live 12.3.6\Preferences\Log.txt" -Tail 200
+```
+
+## Verification Steps
+
+1. Confirm Ableton starts without obvious Control Surface load errors.
+2. Confirm `127.0.0.1:9004` is in `Listen` state from Windows.
+3. Run the smoke-test wrapper and confirm the first action remains read-only.
+4. Confirm `ping`, `health_check`, and `get_session_info` all return valid JSON with `"ok": true`.
+5. Review the raw request/response capture and the recent Ableton log tail together.
+6. Confirm the captured `tool_count` and `ableton_version` remain plausible across repeated runs.
+
+## Risks
+
+- This repo still has no event-driven status feed, so the monitor is polling-based and coarse.
+- `health_check` is useful but limited; it reports queue size and version, not full runtime internals.
+- WSL-side socket visibility was unreliable on this machine, so status checks must be treated as Windows-native.
+- The exact Ableton log path can vary by installed version.
+- A successful listener check does not guarantee every action path is implemented correctly.
+
+## Pass/Fail Criteria
+
+Pass:
+
+- Ableton startup evidence is present in the log.
+- Windows shows `127.0.0.1:9004` listening.
+- Read-only status requests succeed consistently.
+- Raw request/response and log evidence are captured together.
+- No core Remote Script changes are required for the monitor workflow.
+
+Fail:
+
+- The script does not load or does not stay loaded.
+- The port is not listening.
+- Read-only requests fail, time out, or return malformed JSON.
+- The monitoring workflow depends on WSL-only checks that do not reflect the real Windows runtime.
+
+## Rollback Approach
+
+- Deselect `ClaudeMCP_Remote` in Ableton Preferences if needed.
+- Remove the deployed control surface copy from the Ableton scripts directory if this POC must be backed out.
+- Delete only additive logs and wrapper outputs.
+- Leave core repo code unchanged.
+
+## Recommendation
+
+Proceed with POC 02 as a documentation-and-wrapper phase first. Do not introduce a new monitoring subsystem in the Remote Script until repeated Windows-native runs show a stable need for more granular observability.