96 lines
5.3 KiB
Markdown
96 lines
5.3 KiB
Markdown
# MAIN TX watcher usage
|
|
|
|
## Purpose
|
|
|
|
tools/tx_agent_watcher.py is an ordinary local Python process. It polls the small RX result on origin/rx-node and publishes small acknowledgements to origin/tx-node. It does not call an LLM and does not open HackRF hardware.
|
|
|
|
## Start
|
|
|
|
From the repository root, double-click:
|
|
|
|
tools\start_tx_watcher.cmd
|
|
|
|
The visible console polls every 5 seconds. A missing rx-node or tx-node branch, an invalid result or an acknowledgement push failure is reported. No model runs while polling or publishing.
|
|
|
|
## Result history cursor
|
|
|
|
The watcher stores `last_processed_rx_node_commit` in `.local\tx_agent_watcher_state.json`. After each fetch it enumerates every commit in:
|
|
|
|
last_processed_rx_node_commit..origin/rx-node
|
|
|
|
It reads `RX_RESULT.json` from each exact commit and processes the commits from oldest to newest. READY therefore remains observable when READY and COMPLETE are both published between two polling cycles.
|
|
|
|
The cursor advances only after that commit has been read, validated, handled and, when required, acknowledged successfully. A failed acknowledgement push leaves the RX commit unprocessed so that the next poll retries it. A malformed intermediate commit blocks later commits until the defect is corrected. A non-fast-forward rewrite of `rx-node` is rejected. Duplicate result content is suppressed, but its commit is still marked as processed.
|
|
|
|
State format version 2 retains the existing digest and authorization fields and adds `last_seen_commit` and `last_processed_rx_node_commit`. A version-1 digest-only state is mapped to the newest matching commit in the existing result history. Back up the local state before manual recovery; do not delete it blindly.
|
|
|
|
## MAIN acknowledgements
|
|
|
|
After it handles a channel-test READY or COMPLETE event, the watcher publishes a strict acknowledgement to origin/tx-node. Each acknowledgement binds the exact `SOURCE_RX_COMMIT`, canonical `SOURCE_RX_DIGEST` and RX result `SOURCE_HEAD`. The channel-test states are:
|
|
|
|
CHANNEL_READY_OBSERVED
|
|
CHANNEL_COMPLETE_OBSERVED
|
|
|
|
The tx-node branch is independent of video-development. Every commit tree may contain only:
|
|
|
|
docs/handoff/results/TX_RESULT.json
|
|
docs/handoff/results/TX_RESULT.md
|
|
|
|
Each file is limited to 64 KiB. Before committing, the publisher compares the complete staged path set with this allowlist. It suppresses an acknowledgement that already exists for the same task, state, RX commit, digest, source HEAD and RF safety values. The RX laptop scans the full tx-node history from oldest to newest, so two acknowledgements published between polls remain observable.
|
|
|
|
The acknowledgement operation is ordinary Python and Git. It does not invoke ChatGPT, Codex or another model. It stores no IQ, video, waveform, source code, large logs or local state on tx-node.
|
|
|
|
## READY and RED approval
|
|
|
|
RF_HANDOFF_CHANNEL_TEST_001 READY and COMPLETE states are recorded and acknowledged without a RED prompt and never open the production gate.
|
|
|
|
For a fresh valid RF001A_OTA_CAPTURE_004 READY result, the watcher checks the expected source HEAD, current origin/rx-node commit, common clock and capture window. It then prints the task ID, capture start and expected end and asks for:
|
|
|
|
AUTHORIZE RF TX
|
|
|
|
Any other input blocks authorization.
|
|
|
|
After the exact phrase, the watcher fetches rx-node again. It requires the same result digest and commit, the expected source HEAD, a fresh publication, an active 60-second capture window, verified common clock and at least 10 seconds remaining. An expired historical READY is recorded as observed but cannot create an authorization.
|
|
|
|
On success it writes:
|
|
|
|
.local\tx_authorizations\RF001A_OTA_TX_004_authorized.json
|
|
|
|
The watcher also publishes `TX_AUTHORIZED` to origin/tx-node. This record opens
|
|
the gate for the separately controlled TX executor. The watcher itself does
|
|
not run hackrf_transfer. The record explicitly says `rf_tx_started = false`
|
|
and `rf_tx = 0`.
|
|
|
|
At actual process start the executor publishes `TX_STARTED` with the most
|
|
accurate available UTC timestamp. After process exit it publishes
|
|
`TX_COMPLETE` with finish time, integer exit code, underruns and errors. These
|
|
events preserve the exact RX READY commit and digest binding. They do not
|
|
replace verification of packets from captured IQ.
|
|
|
|
The executor writes each strict schema-version-2 event JSON outside Git, then
|
|
uses the model-free publisher:
|
|
|
|
python -B tools/tx_agent_watcher.py --publish-tx-event <event-json> --acknowledgement-branch tx-node
|
|
|
|
The publisher requires a clean, current `video-development` checkout. A
|
|
`TX_STARTED` event requires a matching `TX_AUTHORIZED` in tx-node. A
|
|
`TX_COMPLETE` event also requires the matching `TX_STARTED` timestamp.
|
|
|
|
The TX executor must re-fetch rx-node and compare the result commit and digest immediately before hardware access.
|
|
|
|
## Stop
|
|
|
|
Double-click:
|
|
|
|
tools\stop_tx_watcher.cmd
|
|
|
|
The stop command writes a local stop request and waits for the watcher PID to clear.
|
|
|
|
## Fake mode
|
|
|
|
Automated tests use a local bare Git repository. For a single local JSON fixture, the CLI dry-run form is:
|
|
|
|
python -B tools/tx_agent_watcher.py --dry-run --once --result-file <ready-json> --approval authorize
|
|
|
|
The --approval option is rejected outside --dry-run. Fake mode writes a local fake authorization and never fetches the production remote or accesses SDR hardware.
|