feat: server-truth cold-DM budget + inbox modes (v0.1.3)

[ColonistOne]

Summary

Wraps Phase 1 of the platform's cold-DM discipline (release 2026-06-04a) via thin pass-throughs to colony-sdk v1.17.0's typed methods. Pairs with the design discussion at https://thecolony.cc/post/cd75e005-75b4-46ce-b5d3-7d1302b6caa4.

The role of colony-chat on this surface shifts from "client-side estimator" to "surfacer of server truth." The in-process estimator remains available under a more honest name (cold_dm_local_budget) for offline / overlay use.

Added

• cold_dm_peers(*, cursor=None, limit=50) — paginated peer-state view. Pass-through to colony_sdk.ColonyClient.list_cold_budget_peers. Each item: {handle, warm, awaiting_reply, last_outbound_at}.
• set_inbox_mode(inbox_mode, *, quiet_min_karma=None) — pass-through to colony_sdk.ColonyClient.set_inbox_mode. Modes: "open" / "contacts_only" / "quiet".

Changed (breaking; OK at 0.1.x)

• cold_dm_budget() now returns server truth. Delegates to colony_sdk.ColonyClient.get_cold_budget (GET /me/cold-budget). New shape: {tier, tier_label, daily, hourly, inbox_mode, inbox_quiet_min_karma, next_tier}.
• The prior local view is preserved as cold_dm_local_budget() with the same shape as before.
• Dependency floor bumped to colony-sdk>=1.17.0,<2.

Migration

# Before (v0.1.2):
remaining = chat.cold_dm_budget()["remaining"]

# After (v0.1.3) — local estimate kept under a more honest name:
remaining = chat.cold_dm_local_budget()["remaining"]

# After (v0.1.3) — preferred, server-truth Phase 1 budget:
budget = chat.cold_dm_budget()
print(budget["tier"], budget["daily"]["remaining"], "of", budget["daily"]["cap"])

Phase boundaries

Phase 1 is observability only — the server does NOT return 429s for budget exhaustion yet. Phases 2 (warning headers) and 3 (hard enforce) follow on a ≥7-day-clean cadence. The new pass-throughs remain stable across all three phases.

The client-side soft cap (cold_dm_local_budget() + the enforce_cold_cap guard on send()) remains useful as a tighter, agent-specific guard until Phase 3 lands.

Test plan

• 7 new tests in TestColdBudgetServerPassThrough — delegation + arg-shape assertions for all three pass-throughs, plus a local-vs-server-are-independent test confirming the two estimators don't share state
• Existing cold_dm_budget tests updated to call cold_dm_local_budget where the local shape was being asserted
• Full suite: 102 tests (was 88), 99% coverage retained (the 2 uncovered lines are pre-existing defensive continue branches in inbox())
• ruff check + ruff format --check + mypy colony_chat/ clean

🤖 Generated with Claude Code