# RX watcher usage

## START

On the RX laptop, pull `video-development`, install the project's normal Python dependencies, then double-click:

```text
tools\start_rx_watcher.cmd
```

The watcher stays in a visible console and polls `origin/video-development` every 30 seconds. The interval is configurable with `--poll-interval`. 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:

```text
NEW TASK DETECTED

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

Choose `[A] Approve`, `[D] Defer` or `[S] Stop watcher`. An RF TX task also requires the exact separate phrase `AUTHORIZE RF TX`; another RED task requires `AUTHORIZE <TASK_ID>`. This only opens the executor gate; the first version's `ManualExecutor` still performs no RF action and starts no model.

## APPROVE

After approval, open:

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

Transfer that prepared task to the chosen agent manually. Fill the adjacent `RX_RESULT.md` and `RX_RESULT.json` with measured results. When work is actually complete, run:

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

Do not claim completion merely because the prompt was prepared.

## DONE and result publication

If the task says `ALLOW_PUSH = RX_RESULT_ONLY` and the user separately authorizes publication, publish only small result Markdown/JSON and log metadata to `rx-node`. Never commit or push from the RX laptop to `video-development`. Do not put raw IQ, video or waveform files in Git.

## STOP

Double-click:

```text
tools\stop_rx_watcher.cmd
```

The script creates a local stop request and waits for the watcher PID to clear. The approval prompt is interruptible on Windows, and the polling delay checks the stop request every 0.1 seconds. A successful stop prints `WATCHER STOPPED`; no polling process remains.

## DRY RUN

From the repository root:

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

Expected behavior: the fake task is detected, approved and written under `.local/rx_agent_outbox/WATCHER_TEST_001/`. No Git fetch, SDR access, agent call, RF RX/TX, commit or push occurs. Delete `.local/` at any time if the local state and outbox are no longer needed.

## Executor availability

Version 1 always provides `ManualExecutor`. Before adding or selecting a Codex backend on RX, run `Get-Command codex` on that laptop and verify a harmless local invocation. Do not infer RX availability from the main PC.