105 lines
4.3 KiB
Markdown
105 lines
4.3 KiB
Markdown
# 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. For RF001A_OTA_CAPTURE_004 it also verifies the required historical acknowledgements on origin/tx-node and performs the authenticated no-change rx-node write preflight before offering the task for approval.
|
|
|
|
## 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_004, first require the watcher to print:
|
|
|
|
RX-NODE WRITE PREFLIGHT = PASS
|
|
|
|
MAIN READY RECEIVED = CONFIRMED
|
|
MAIN COMPLETE RECEIVED = CONFIRMED
|
|
|
|
These confirmations come from the full origin/tx-node history. They must bind the known channel-test RX commits and canonical digests. The RX watcher stores the two digests and the matching tx-node commit hashes in its local state. A missing branch, wrong digest, wrong RX commit, wrong source HEAD, malformed intermediate acknowledgement or rewritten history blocks the task.
|
|
|
|
Do not rerun RF_HANDOFF_CHANNEL_TEST_001 merely to recreate these confirmations. After this gate and the task's YELLOW approval, create the strict READY JSON outside Git only after CLKIN is detected, the capture child is alive and the file is growing. 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, the independently confirmed RX RESULT REMOTE HEAD, and RF TX = 0. Report RX READY FOR TX = YES only after the remote HEAD equals the result commit.
|
|
|
|
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.
|
|
|
|
Immediately before hardware access, repeat the same non-mutating check:
|
|
|
|
python -B tools/rx_agent_watcher.py --check-result-write --result-branch rx-node
|
|
|
|
The READY publisher retries only one recognized transient failure. It checks
|
|
the remote before retrying and pushes the same immutable commit; it does not
|
|
create a replacement READY commit.
|
|
|
|
## Verified model-free channel evidence
|
|
|
|
The completed RF_HANDOFF_CHANNEL_TEST_001 evidence is bound to READY commit `4cb6c8cad1ab5194755c2740c2a5a83933d099d8` and COMPLETE commit `83d91ff5309777ab639a24f774e9d0b8825a11e9`. The RX watcher accepts the gate only after origin/tx-node contains the matching MAIN acknowledgements. This read-only check performs no capture and keeps RF TX at 0.
|
|
|
|
## 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.
|