perf: dirty-flag polling for channel unread checks

[laynepenney]

Summary

• Adds unread_flags table to channels SQLite DB for O(1) unread checks
• channel_has_unread() returns in <1ms when nothing changed (single SQLite read vs JSONL scan)
• Flag set on post/directive/pin writes for all other channel members
• Flag cleared only by channel_read() (full read), NOT by channel_unread() (count-only)
• Backward compatible: existing channel_unread() behavior unchanged

Changes

• channel.py: Added unread_flags table schema, _set_dirty_flags() helper, channel_has_unread() function, dirty-flag set in _append_message and channel_pin, dirty-flag clear in channel_read
• test_channel.py: 10 new tests covering write-flag-read-clear lifecycle

Premium boundary: this is OSS recall infrastructure. The dirty-flag optimization benefits all agents polling channels, reducing per-poll cost from O(channels x JSONL_size) to O(1).

Test plan

• 10 new dirty-flag tests pass
• Full channel test suite: 192 passed, 0 failed
• Full repo test suite: 1972 passed, 19 skipped, 0 failures

Closes #638

🤖 Generated with Claude Code

[github-actions]

Thank you for your contribution! Before we can merge this PR, we need you to sign our Contributor License Agreement.

To sign, please comment on this PR with the following exact text:

I have read the CLA Document and I hereby sign the CLA

You can also re-trigger the CLA check by commenting recheck.

---

I have read the CLA Document and I hereby sign the CLA

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}

[laynepenney]

QA review — LGTM.

Design is correct. Dirty flag separate from the read cursor is the right approach — O(1) check without changing existing unread semantics. Key invariants all hold: flag cleared only by channel_read() not channel_unread(), sender excluded from their own flags, join initializes clean, pin and directive both route through _append_message so they set flags correctly.

Tests are thorough. 10 tests cover the full lifecycle plus edge cases: count-only doesn't clear (critical invariant), multiple posts single clear, pin sets dirty, directive sets dirty, non-member gets empty dict. Full suite at 1972 passed confirms no regressions.

Minor note (non-blocking): _set_dirty_flags() opens a fresh DB connection rather than receiving one as a parameter. Works fine in practice (tests pass), but if _append_message ever holds an uncommitted write when it calls _set_dirty_flags, the two connections could serialize under SQLite WAL. Consider passing the connection in a future refactor.

Boundary declaration present and correct. Needs one more review.

[laynepenney]

this needs to merge into sprint-17 branch, not main