feat: add msglib receive adapter

docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md

@@ -2720,17 +2720,59 @@ Sidecar bounded DB message listing result:
 - Keep source selection explicit. Do not silently merge MsgLib rows into default MCP receive output.
 - Verification should continue to clear MsgLib env in the standard `verify-go-mcp.ps1`; optional copied-DB verification remains separate.
 
-- [ ] **Step 1: Locate current receive-message model boundary**
+- [x] **Step 1: Locate current receive-message model boundary**
 
-Inspect `internal/isphere` and `internal/tools` receive-message code and decide whether the adapter belongs below the tool layer or inside the tool registration layer.
+Confirmed the domain boundary is `internal/isphere.Message` plus `ReceiveMessagesQuery/Result`; MCP tools depend on a `ReceiveMessagesSource` interface and can keep PacketReader as the default source.
 
-- [ ] **Step 2: Write failing adapter test**
+- [x] **Step 2: Write failing adapter test**
 
-Use a fake MsgLib list provider returning redacted normalized messages and assert mapped receive-message fields, source refs, attachment metadata behavior, and explicit source-selection handling.
+Added `TestMsgLibMessageSourceMapsListMessagesToReceiveMessages`. RED failed because `MsgLibMessageSource` did not exist.
 
-- [ ] **Step 3: Implement minimal adapter and update docs**
+- [x] **Step 3: Implement minimal adapter and update docs**
 
-Implement only enough code to pass the adapter test; defer MCP default wiring until reconciliation/source-selection behavior is proven.
+Added `internal/isphere.MsgLibMessageSource` with injected `ListMessages` provider, explicit include flags, safety-flag checks, source/raw-ref mapping, and bounded attachment metadata mapping. Tool output now honors explicit message source/raw-ref/attachments when present while preserving PacketReader fallbacks.
+
+---
+
+## Loop C39 Result
+
+DB-backed receive source adapter result:
+
+- Added `internal/isphere.MsgLibMessageSource` and `MsgLibMessageLister` interface.
+- Extended `internal/isphere.Message` with optional `Source`, `RawRef`, and `Attachments` fields so DB-backed rows can preserve sidecar refs without changing PacketReader behavior.
+- `internal/tools` receive-message mapping now uses explicit message attachments/source/raw-ref when present and falls back to existing PacketReader-derived behavior otherwise.
+- Unit tests use a fake MsgLib provider only; no real DB is required for C39.
+- MCP default source is unchanged: `auto` still resolves to PacketReader/log-backed behavior.
+
+---
+
+## Loop C40: Explicit MsgLib receive source selection design/test slice
+
+**Goal:** Define and test the operator-facing path that enables MsgLib DB receive rows only through explicit source selection, while preserving PacketReader as the default `auto` behavior.
+
+**Planned files:**
+- Likely modify: `internal/tools/isphere_read.go` and tests for source-selection behavior.
+- Possibly modify: `internal/mcpserver/server.go` only after the tool-layer contract is clear.
+- Modify docs/status/matrix/plan after implementation.
+
+**Planned behavior:**
+- Keep `source_preference="auto"` and empty source preference on the existing PacketReader/log-backed source.
+- Add or design an explicit source value such as `msglib_readonly` for the DB adapter; reject it when no MsgLib receive source is configured.
+- Do not silently merge PacketReader and MsgLib rows.
+- Standard `verify-go-mcp.ps1` should remain deterministic and should not require copied DB env.
+- Optional copied-DB verification can be added only if its printed output stays sanitized.
+
+- [ ] **Step 1: Write source-selection RED test**
+
+Create a fake primary PacketReader source and fake MsgLib receive source; assert default/auto uses primary and explicit MsgLib selection uses the MsgLib source.
+
+- [ ] **Step 2: Implement minimal selector**
+
+Add the smallest selector layer needed by the test. Keep current rejection behavior when explicit MsgLib is requested but not configured.
+
+- [ ] **Step 3: Verify and update operator docs**
+
+Run full verification and update docs to describe the explicit opt-in route and the unchanged default route.
 
 ---
 ## Self-Review