# RX watcher usage

## Start

On the RX laptop, pull video-development and double-click:

    tools\start_rx_watcher.cmd

The watcher stays in a visible console and polls origin/video-development every 30 seconds. It does not start ChatGPT, Codex or another agent.

## Idle

While no new TASK_ID exists, the watcher performs only git fetch, reads the remote task file and compares IDs with .local/rx_agent_state.json. There is no model execution or token use.

## New task

The console shows:

    NEW TASK DETECTED

    TASK ID =
    TITLE =
    SAFETY LEVEL =
    HARDWARE ACCESS =
    RF RX =
    RF TX =

Choose [A] Approve, [D] Defer or [S] Stop watcher. RF TX also requires the exact phrase AUTHORIZE RF TX. Another RED action requires AUTHORIZE <TASK_ID>.

## Approve and execute

After approval, open:

    .local\rx_agent_outbox\<TASK_ID>\TASK.md

Transfer that prepared task to the chosen executor. The watcher records last_approved_task_id, which is required for result publication. Preparing the outbox is not evidence that the hardware task ran.

When the task is actually complete, run:

    python -B tools/rx_agent_watcher.py --mark-completed <TASK_ID>

## Publish READY

For RF001A_OTA_CAPTURE_002, create the strict READY JSON outside Git only after the capture child is alive and the file is growing. Then run:

    python -B tools/rx_agent_watcher.py --publish-result <ready-json-path> --result-branch rx-node

On success, the watcher prints RX RESULT PUBLISH = PUBLISHED or UNCHANGED, the result commit, and RF TX = 0.

The command fails if:

- the task was not approved locally;
- the TASK_ID differs;
- source_head differs from the checkout HEAD;
- origin/rx-node does not exist;
- the schema is invalid;
- Git commit or push fails.

A failed publication is not READY evidence and cannot authorize TX.

## Publish COMPLETE

After capture completion, build the strict final JSON with state CAPTURE_COMPLETE and publish it with the same command:

    python -B tools/rx_agent_watcher.py --publish-result <final-json-path> --result-branch rx-node

Only the two fixed result files are committed. Raw IQ, video, waveform, stdout, stderr and large logs stay outside Git.

## Stop

Double-click:

    tools\stop_rx_watcher.cmd

The script creates a local stop request and waits for the watcher PID to clear. A successful stop prints WATCHER STOPPED.

## Dry run

From the repository root:

    python -B tools/rx_agent_watcher.py --dry-run --once --approval approve --task-file tests/fixtures/watcher_test_task.md

The fake task is written under .local/rx_agent_outbox/WATCHER_TEST_001/. No Git fetch, SDR access, agent call, RF RX, RF TX, commit or push occurs.