🤖 refactor: extract the agent peer-messaging broker from TaskService

[ibetitsmike]

Summary

Extracts the peer/family agent-messaging protocol's admission invariants out of TaskService into a new AgentPeerMessageBroker: sliding-window rate limits (per sender-target pair and per target), duplicate suppression, queued-peer-message capacity, consecutive-peer-wake caps, per-pair/per-target session budgets with idempotent refunds, per-target delivery locks, title capping, and peer envelope/trigger composition. TaskService keeps tree topology, stop-epoch/overlay orchestration, and dispatch, and delegates every admission decision directly (no pass-through wrappers).

Background

Refactor #4 from the 2026-08-29 architecture review (evidence at main @ f04e0f8): taskService.ts inlined the whole protocol across two regions (~5654-6736, ~9612-10097), and every protocol-invariant test had to spin up the 35-method WorkspaceHost mock harness. Protocol invariants now live in one module testable with a fake one-method host and a mock clock.

Behavior-preserving by construction: check ordering, refusal codes, reason strings, retryAfterMs math, and budget charge arithmetic are byte-identical to the pre-refactor code.

Net LOC delta

	added	removed	net
Production (agentPeerMessageBroker.ts + taskService.ts)	271	286	-15
Tests (agentPeerMessageBroker.test.ts + taskService.test.ts)	238	561	-323
Total	509	847	-338

Harness-heavy tests that only re-asserted pure invariants through the full TaskService stack were deleted and replaced by table-driven broker tests; one thin delegation test per route (peer rate-limit refusal, task_message_parent and sibling budget exhaustion) plus every test covering behavior the broker cannot see (refund-on-dispatch-failure, charge-at-admission ordering, stop races, envelope-row persistence, delivery serialization) were kept. The only irreducible addition is the broker's structural boilerplate (imports, class/constructor, the local one-method host interface), which is what makes the invariants independently testable.

The broker declares its own minimal host interface (countQueuedAgentPeerMessages) instead of importing from taskWorkspaceSeam.ts, keeping this diff merge-independent from the parallel WorkspaceHost role-interface split.

Validation

• Remote dogfood UAT (Coder Agents): PASS on ae9bf3e93 — live Xum UI multi-agent tree across descendant/sibling/ancestor relations, an independent 22-assertion edge-case probe (rate/dedupe/wake/budget boundaries at exact ceilings, refund idempotence), and a source-level cross-check of every refusal string and retry computation against f04e0f8. The one commit since (daa28db4f) is cosmetic (test-cast type reuse), revalidated locally.
• bun test src/node/services/agentPeerMessageBroker.test.ts: 12/12.
• bun test src/node/services/taskService.test.ts: 514 pass; the 2-3 sporadic failures (terminal recovery ... x2, higher-ancestor waiters ...) reproduce identically on pristine origin/main in this environment (config.json atomic-write chown/rename ENOENT under /tmp) and are unrelated to this diff.
• make static-check: green.

Risks

Low. The moved logic is byte-identical and the delegation points are 1:1 at existing callsites; the riskiest surface (admission/charge ordering under concurrent sends) is covered by kept integration tests and the broker's check-order test (queued-count host query is only reached after in-memory checks pass).

---

Generated with xum • Model: anthropic:claude-fable-5 • Thinking: xhigh • Cost: $37.96

[ibetitsmike]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit: daa28db4f4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".