agent: surface ACK_FLASH_ERROR instead of returning empty bytes (#101)

## Summary

- `FlashAgentClient.read_memory()` previously broke its accumulator loop
on **any** `RSP_ACK` and returned the buffer as-is. When the agent
rejected the address — e.g. a probe outside the V3+/V4+ I/O whitelist in
`agent/main.c:addr_readable` — that meant `b\"\"` silently. Now it
inspects the ACK status byte and raises `RuntimeError(\"Read rejected by
agent: status=0x02 …; addr=… size=…\")`.
- `FlashAgentClient.crc32()` had the same shape — a clean `RSP_ACK`
rejection was reported as a generic \"CRC32 response invalid\". Now it
explicitly detects the ACK and reports the status.
- Adds the missing `ACK_FLASH_ERROR = 0x02` to
`src/defib/agent/protocol.py` (it already existed in
`agent/protocol.h`). Updates the existing membw rejection test to
reference the constant.

## Context

Surfaced while studying flash on an eMMC-based hi3516av300 over the
running agent. The eMMC controller MMIO lives at
`0x10100000..0x101FFFFF` which isn't in the agent's V3+/V4+ whitelist;
probing there silently returned `b\"\"` for ~30s of wall time across
multiple addresses, leading to wasted debugging.

## Test plan

- [x] `uv run pytest tests/ -x --ignore=tests/fuzz` — 496 passed, 2
skipped
- [x] `uv run ruff check src/defib/agent/ tests/test_agent_protocol.py`
— clean
- [x] `uv run mypy src/defib/agent/ --ignore-missing-imports` — clean
- [x] Verified on real hardware (hi3516av300, eMMC D9D16): probing
`0x10100000` now reports `Read rejected by agent: status=0x02 (outside
agent's readable whitelist or flash read failed); addr=0x10100000
size=64` instead of returning empty bytes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Dmitry Ilyin <widgetii@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: widgetii

src/defib/agent/client.py

@@ -15,6 +15,7 @@
 from typing import Callable
 
 from defib.agent.protocol import (
+    ACK_FLASH_ERROR,
     ACK_OK,
     CMD_CRC32,
     CMD_ERASE,
@@ -320,6 +321,13 @@ async def read_memory(
                 if on_progress:
                     on_progress(len(received), size)
             elif cmd == RSP_ACK:
+                status = data[0] if data else 0
+                if status != ACK_OK:
+                    detail = "outside agent's readable whitelist or flash read failed" if status == ACK_FLASH_ERROR else "agent error"
+                    raise RuntimeError(
+                        f"Read rejected by agent: status=0x{status:02x} "
+                        f"({detail}); addr={addr:#010x} size={size}"
+                    )
                 break
             else:
                 raise RuntimeError(f"Unexpected response: cmd=0x{cmd:02x}")
@@ -627,6 +635,13 @@ async def crc32(self, addr: int, size: int) -> int:
         # chips (DMA reads, multi-MB/s) still get plenty of headroom.
         timeout = max(15.0, 5.0 + size / (100 * 1024))
         cmd, data = await recv_response(self._transport, timeout=timeout)
+        if cmd == RSP_ACK:
+            status = data[0] if data else 0
+            detail = "outside agent's readable whitelist or flash read failed" if status == ACK_FLASH_ERROR else "agent error"
+            raise RuntimeError(
+                f"CRC32 rejected by agent: status=0x{status:02x} "
+                f"({detail}); addr={addr:#010x} size={size}"
+            )
         if cmd != RSP_CRC32 or len(data) < 4:
             raise RuntimeError("CRC32 response invalid")
         return int(struct.unpack("<I", data[:4])[0])

src/defib/agent/protocol.py

@@ -62,9 +62,10 @@
 RSP_SCAN = 0x86
 RSP_MEMBW = 0x87
 
-# ACK status
+# ACK status (must match agent/protocol.h)
 ACK_OK = 0x00
 ACK_CRC_ERROR = 0x01
+ACK_FLASH_ERROR = 0x02
 
 FRAME_DELIMITER = 0x00
 MAX_PACKET_SIZE = 1100  # Max COBS-encoded packet size

tests/test_agent_protocol.py

@@ -11,6 +11,7 @@
 from defib.agent.protocol import (
     ACK_OK,
     ACK_CRC_ERROR,
+    ACK_FLASH_ERROR,
     CMD_INFO,
     CMD_READ,
     CMD_SELFUPDATE,
@@ -831,6 +832,42 @@ async def test_armv5_rejection_raises(self):
         client = FlashAgentClient(t)
         assert await client.connect(timeout=1.0)
 
-        t.enqueue_rx(make_device_packet(_RSP_ACK, bytes([0x02])))  # ACK_FLASH_ERROR
+        t.enqueue_rx(make_device_packet(_RSP_ACK, bytes([ACK_FLASH_ERROR])))
         with pytest.raises(RuntimeError, match="rejected"):
             await client.membw()
+
+
+class TestReadCrcRejection:
+    """When the agent rejects a CMD_READ / CMD_CRC32 (e.g. addr outside
+    addr_readable whitelist), the client must surface a clear error
+    rather than silently returning empty bytes or a generic 'invalid'."""
+
+    @pytest.mark.asyncio
+    async def test_read_memory_raises_on_flash_error_ack(self):
+        from defib.transport.mock import MockTransport
+        from defib.agent.client import FlashAgentClient
+
+        t = MockTransport(flush_clears_buffer=False)
+        t.enqueue_rx(make_device_packet(RSP_READY, b"DEFIB"))
+        client = FlashAgentClient(t)
+        assert await client.connect(timeout=1.0)
+
+        # Agent immediately rejects with ACK_FLASH_ERROR (e.g. whitelist miss)
+        t.enqueue_rx(make_device_packet(RSP_ACK, bytes([ACK_FLASH_ERROR])))
+        with pytest.raises(RuntimeError, match="Read rejected"):
+            # Use fast=False to skip baud-switch path
+            await client.read_memory(0x10100000, 64, fast=False)
+
+    @pytest.mark.asyncio
+    async def test_crc32_raises_on_flash_error_ack(self):
+        from defib.transport.mock import MockTransport
+        from defib.agent.client import FlashAgentClient
+
+        t = MockTransport(flush_clears_buffer=False)
+        t.enqueue_rx(make_device_packet(RSP_READY, b"DEFIB"))
+        client = FlashAgentClient(t)
+        assert await client.connect(timeout=1.0)
+
+        t.enqueue_rx(make_device_packet(RSP_ACK, bytes([ACK_FLASH_ERROR])))
+        with pytest.raises(RuntimeError, match="CRC32 rejected"):
+            await client.crc32(0x10100000, 64)