feat: channel seam hooks for premium coordination gating (#553)

[laynepenney]

Summary

• Add register_message_hook() to channel.py — premium coordination layer can wire in @mention storage and wake emission without coupling into the OSS substrate
• Gate coordination action handlers (directive, claim, board, mute, kick, broadcast) behind premium in the action registry — without the premium plugin, these show as "locked"
• Default hooks auto-register for backward compatibility — existing behavior unchanged
• 228 tests pass (192 existing + 11 hook + 25 registry)

Premium boundary: core OSS (channel substrate + action registry seam).

Paired with premium PR for the coordination plugin module.

Test plan

• 11 new hook mechanism tests (fire, order, exception safety, clear, defaults)
• 5 new registry gating tests (locked without premium, available after registration, tier check)
• 192 existing channel tests pass unchanged
• Updated existing test for new gating behavior

🤖 Generated with Claude Code

[github-actions]

All contributors have signed the CLA. Thank you!
_{Posted by the CLA Assistant Lite bot.}

[laynepenney]

Opus review (1/2): Hook mechanism

Clean extraction. The hook pattern in _append_message is the right abstraction: OSS fires hooks after write, premium can replace or extend them via _clear_message_hooks() + register_message_hook(). Exception safety (bare except + pass) is appropriate for best-effort hooks.

One nit: from typing import Callable at line ~135 inside the file body rather than at top with other imports. Not blocking but worth noting for consistency.

Default hooks auto-registering at module load time maintains backward compatibility. LGTM.

[laynepenney]

Opus review (2/2): Gating + boundary

The coordination action gating is well-structured: without premium, directive/claim/board/etc. return "requires premium" instead of silently failing. register_coordination_handlers() is the public API premium calls to unlock them.

Tests are thorough: 11 hook tests + 5 registry gating tests cover the critical paths. The tearDown/setUp pattern properly resets global state between tests.

Premium boundary: OSS (channel substrate + action registry seam). Correct.

LGTM. Ready for merge after Layne's review.

[laynepenney]

Sentinel self-review (1/2) -- channel hook seam.

Design decisions:

• Hooks are a list (not a single callback) so premium can add multiple hooks or replace them
• Default hooks auto-register at module load for backward compatibility
• _clear_message_hooks() exposed for tests and for premium to reset before registering its own
• Hooks are best-effort (exceptions caught) so a broken hook never prevents message delivery
• _set_dirty_flags stays in _append_message (not a hook) because it's OSS unread infrastructure

Test coverage: 11 hook tests + 5 registry gating tests + 192 existing channel tests = 228 total.

[laynepenney]

Sentinel self-review (2/2) -- sprint checklist.

• OSS/premium boundary declaration in PR description
• Tests pass (228 total)
• Backward compatible (default hooks maintain existing behavior)
• Awaiting Opus review (Sprint 18 rule: Opus reviews every PR)

Depends on: nothing (standalone OSS change)
Blocks: premium#593 (coordination plugin imports register_coordination_handlers from this)

[laynepenney]

Review pass: no new blocking issue from this slice.

The OSS hook seam and action-registry gating line up with the current Sprint 18 boundary: substrate + registry seam stay OSS; coordination handlers stay on the premium side. My earlier packaging concern was on the provider seam PRs, not this channel split slice.

[laynepenney]

Follow-up on CI state: the matrix is currently red on an unrelated existing test failure in tests/recall/test_channel_worktree.py (ModuleNotFoundError: No module named "tests" from from tests.recall.test_channel import _patch_data_dir). I filed that separately so this seam PR is not conflated with the broken test harness.

Tracker: recall#669

[laynepenney]

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

[laynepenney]

recheck

[laynepenney]

recheck