Add MAIN-to-RX acknowledgement channel

docs/handoff/NEXT_RX_TASK.md

@@ -21,19 +21,30 @@ START COORDINATED RF-001A COMMON-CLOCK OTA CAPTURE
 
 This is a new YELLOW task. Do not reuse approval or completion state from RF001A_OTA_CAPTURE_001, RF001A_OTA_CAPTURE_002 or any earlier task.
 
-One approval for this task covers the model-free channel test, read-only checks, one bounded RF RX capture and publication of the two small allowlisted result files to the existing rx-node branch. It never authorizes RF TX.
+One approval for this task covers the read-only bidirectional channel check, other read-only checks, one bounded RF RX capture and publication of the two small allowlisted result files to the existing rx-node branch. It never authorizes RF TX.
 
 The preceding RF001A_OTA_CAPTURE_002 produced a real 120.1413067 s, 1920000000-byte capture with CLKIN detected before and after, zero reported overruns and SHA256 99a3e7cb51d3ad4e3b914b63da0695ed6658aa169110c32659aba995b542fa0c. Its READY publication failed, its exact child exit code was not recorded and no synchronized truth metadata was available. Treat that as historical evidence only.
 
-## 1. Model-free handoff channel gate
+## 1. Bidirectional handoff channel gate
 
-After the user chooses [A] Approve for this exact TASK_ID, run before any hardware access:
+Before offering this task for YELLOW approval, the RX watcher must fetch origin/rx-node and origin/tx-node and scan the acknowledgement history from oldest to newest. It must confirm both exact records:
 
-    python -B tools/rf_handoff_smoke.py --hold-seconds 7
+    STATE = CHANNEL_READY_OBSERVED
+    SOURCE_RX_COMMIT = 4cb6c8cad1ab5194755c2740c2a5a83933d099d8
+    SOURCE_RX_DIGEST = 23fc54f1f788f068fd4a842daf0a445bd4ec192866b4d89406c74f1797a9952b
 
-This subtask uses TASK_ID RF_HANDOFF_CHANNEL_TEST_001. It accesses no SDR and keeps RF TX = 0. It publishes fake READY and COMPLETE results through the real origin of the main RX checkout. Require the MAIN watcher to observe both states, require confirmed remote commit hashes, and require COMPLETE to remain as the final origin/rx-node state. Require the MAIN watcher state to contain both channel_test_ready_digest and channel_test_complete_digest for this run.
+and:
 
-If any channel check or publication fails, do not access HackRF, do not start capture and STOP with RF TX = 0.
+    STATE = CHANNEL_COMPLETE_OBSERVED
+    SOURCE_RX_COMMIT = 83d91ff5309777ab639a24f774e9d0b8825a11e9
+    SOURCE_RX_DIGEST = 7d98ed2e70e98a087b968c0d65fb1db4277b81f251e075d20583de2e5002b2d6
+
+Both acknowledgements must use TASK_ID RF_HANDOFF_CHANNEL_TEST_001, the original shared source HEAD and RF_TX = 0. Required watcher output:
+
+    MAIN READY RECEIVED = CONFIRMED
+    MAIN COMPLETE RECEIVED = CONFIRMED
+
+Do not rerun the channel test. If origin/tx-node is missing or either exact acknowledgement is absent or invalid, do not access HackRF, do not start capture and STOP with RF TX = 0.
 
 ## 2. Preconditions
 

docs/handoff/RF_HANDOFF_CHANNEL_TEST.md

@@ -12,7 +12,7 @@ RISK_LEVEL = GREEN
 
 # Model-free handoff channel test
 
-Run this gate before RF001A_OTA_CAPTURE_003 and while the MAIN watcher is active:
+The real-origin gate was completed before RF001A_OTA_CAPTURE_003 with:
 
     python -B tools/rf_handoff_smoke.py --hold-seconds 7
 
@@ -21,7 +21,9 @@ The script uses the real origin configured in the main RX checkout. It publishes
     docs/handoff/results/RX_RESULT.json
     docs/handoff/results/RX_RESULT.md
 
-The MAIN watcher must observe both states and must not request RED approval. Its state file must record both channel_test_ready_digest and channel_test_complete_digest. The final remote state must be CAPTURE_COMPLETE, with rx_ready_for_tx false. A synthetic READY state must not remain active.
+The verified READY commit is `4cb6c8cad1ab5194755c2740c2a5a83933d099d8`; its canonical digest is `23fc54f1f788f068fd4a842daf0a445bd4ec192866b4d89406c74f1797a9952b`. The verified COMPLETE commit is `83d91ff5309777ab639a24f774e9d0b8825a11e9`; its canonical digest is `7d98ed2e70e98a087b968c0d65fb1db4277b81f251e075d20583de2e5002b2d6`.
+
+The MAIN watcher observed both states without requesting RED approval. The RX watcher must now verify corresponding CHANNEL_READY_OBSERVED and CHANNEL_COMPLETE_OBSERVED records in the full origin/tx-node history. Do not rerun this channel test only to recreate MAIN confirmation.
 
 The script and watcher do not access SDR hardware, do not run hackrf_transfer and do not authorize any RF transmission.
 

docs/handoff/RX_AGENT_PROTOCOL.md

@@ -4,7 +4,9 @@
 
 The RX laptop watches origin/video-development with ordinary local Python code. Git polling does not call an LLM, ChatGPT or an agent. A detected task is not prepared until the user approves it.
 
-The reverse result channel uses the separate origin/rx-node branch. The RX laptop publishes small machine-readable readiness and completion results. The MAIN PC reads those results without merging rx-node into video-development.
+The RX-to-MAIN result channel uses the separate origin/rx-node branch. The RX laptop publishes small machine-readable readiness and completion results. The MAIN PC reads those results without merging rx-node into video-development.
+
+The MAIN-to-RX acknowledgement channel uses the independent origin/tx-node branch. The MAIN watcher publishes evidence that it observed one exact rx-node commit and digest. The RX laptop scans the acknowledgement history without merging tx-node into video-development.
 
 ## Task header
 
@@ -57,7 +59,9 @@ State includes:
 - last_approved_task_id;
 - deferred_task_id;
 - running;
-- watcher PID.
+- watcher PID;
+- confirmed channel-test READY and COMPLETE digests;
+- matching tx-node acknowledgement commits.
 
 ManualExecutor writes TASK.md, RX_RESULT.md and RX_RESULT.json after approval. It does not invoke an agent, access SDR hardware, commit or push.
 
@@ -122,7 +126,11 @@ For RF_HANDOFF_CHANNEL_TEST_001 the watcher records synthetic READY and COMPLETE
 
 After the phrase, it fetches rx-node again and repeats every check. A changed result or commit, stale publication or fewer than 10 seconds remaining blocks authorization. Historical READY is still observed in order, but an expired capture window never authorizes TX.
 
-The history cursor advances only after successful schema validation and handling. Duplicate content advances the commit cursor without repeating an action. A malformed intermediate result blocks later commits, and a non-fast-forward branch rewrite is rejected.
+The history cursor advances only after successful schema validation, handling and required acknowledgement publication. Duplicate content advances the commit cursor without repeating an action. A malformed intermediate result blocks later commits, and a non-fast-forward branch rewrite is rejected.
+
+For each successfully handled channel-test event, the MAIN watcher publishes a strict TX_RESULT to origin/tx-node. The object contains task ID, acknowledgement state, exact source RX commit and digest, source HEAD, actual observation timestamp, watcher PID and RF safety fields. A channel-test acknowledgement always has RF_TX_AUTHORIZED false, RF_TX_STARTED false and RF_TX 0.
+
+The tx-node publisher stages exactly `docs/handoff/results/TX_RESULT.json` and `docs/handoff/results/TX_RESULT.md`, checks the staged path allowlist and enforces 64 KiB per file. A push failure prevents the rx-node cursor from advancing. Duplicate acknowledgements are suppressed by their source binding. No local state, code, IQ, video, waveform or large log is published.
 
 A successful gate writes one local authorization record under .local/tx_authorizations/. The record has rf_tx_started = false and rf_tx = 0. The separately controlled TX executor must re-fetch and compare the result commit and digest immediately before opening hardware.
 
@@ -137,8 +145,8 @@ Duplicate result digests are not shown repeatedly.
 - Neither watcher starts RF TX.
 - The TX executor remains a separate RED-controlled action.
 
-## Model-free channel and dry-run contracts
+## Bidirectional channel and dry-run contracts
 
-The preflight channel command publishes synthetic READY and COMPLETE results with TASK_ID RF_HANDOFF_CHANNEL_TEST_001 through the real origin. The MAIN watcher must observe both without a RED prompt, and COMPLETE must be the final remote state. It does not access SDR hardware or run hackrf_transfer.
+The completed preflight channel command published synthetic READY and COMPLETE results with TASK_ID RF_HANDOFF_CHANNEL_TEST_001 through origin/rx-node. The MAIN watcher observed both without a RED prompt. The RX watcher now requires exact matching acknowledgements in origin/tx-node before RF001A_OTA_CAPTURE_003 can pass its software gate.
 
-Automated coordination tests use a temporary local bare Git repository and branch named rx-node. They cover worktree publication, READY, COMPLETE, push failure and watcher reception without accessing the real remote or SDR hardware and without transmitting RF.
+Automated coordination tests use a temporary local bare Git repository and independent rx-node and tx-node branches. They cover exact commit and digest binding, duplicate suppression, two commits between polls, stale acknowledgement rejection, missing tx-node, push failure, non-fast-forward protection and a full fake two-way flow without accessing the real remote or SDR hardware and without transmitting RF.

docs/handoff/RX_AGENT_USAGE.md

@@ -10,7 +10,7 @@ The watcher stays in a visible console and polls origin/video-development every
 
 ## 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.
+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_003 it also verifies the required historical acknowledgements on origin/tx-node before offering the task for approval.
 
 ## New task
 
@@ -41,7 +41,14 @@ When the task is actually complete, run:
 
 ## Publish READY
 
-For RF001A_OTA_CAPTURE_003, first complete RF_HANDOFF_CHANNEL_TEST_001. Then create the strict READY JSON outside Git only after CLKIN is detected, the capture child is alive and the file is growing. Run:
+For RF001A_OTA_CAPTURE_003, first require the watcher to print:
+
+    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
 
@@ -58,13 +65,9 @@ The command fails if:
 
 A failed publication is not READY evidence and cannot authorize TX.
 
-## Model-free channel test
+## Verified model-free channel evidence
 
-Before hardware access, while the MAIN watcher is running, execute:
-
-    python -B tools/rf_handoff_smoke.py --hold-seconds 7
-
-It publishes synthetic READY and COMPLETE results through the real origin. Require the MAIN watcher to observe both and require COMPLETE as the final remote state. Failure blocks the hardware capture. REAL RX remains NOT_RUN and RF TX remains 0.
+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
 

docs/handoff/TX_AGENT_USAGE.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-tools/tx_agent_watcher.py is an ordinary local Python process. It polls the small RX result on origin/rx-node. It does not call an LLM and does not open HackRF hardware.
+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
 
@@ -10,7 +10,7 @@ From the repository root, double-click:
 
     tools\start_tx_watcher.cmd
 
-The visible console polls every 5 seconds. A missing rx-node branch or invalid result is reported. No model runs while polling.
+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
 
@@ -20,13 +20,29 @@ The watcher stores `last_processed_rx_node_commit` in `.local\tx_agent_watcher_s
 
 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 and handled successfully. 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.
+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 without a RED prompt and never open the production gate.
+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_003 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: