🤖 refactor: unify agent tree message dispatch behind one relation pipeline

[ibetitsmike]

Summary

Unifies the four agent-tree message dispatch paths in taskService.ts (descendant guidance, peer/ancestor task_send_message, and the parent/sibling RLM family-message routes) behind one relation-parameterized sendTreeMessage pipeline. The four public methods keep their exact signatures, result/error shapes, and delivery semantics; they are now thin wrappers that build a relation spec and enter the shared pipeline.

Background

Card 3 of the 2026-08-31 architecture review. PR #4010 centralized peer-messaging admission invariants (throttles, budgets, envelope prep) in agentPeerMessageBroker.ts, but the four dispatch paths still each reimplemented the same ritual: validate topology, admission refusals, envelope/payload construction, budget reservation, delivery lock, dispatch, refund accounting. The same char-cap, budget, envelope, and lock logic appeared up to four times with only the relationship check differing (~1,150 lines).

Implementation

• One private sendTreeMessage(spec) pipeline owns the shared phase order (normalize/cap, topology, refusals, envelope, budget, lock, dispatch, refund accounting), parameterized by a relation-discriminated spec. Overloads keep each public route's result type exact.
• The trusted descendant machinery (queued-prompt splice, reactivation, live guidance reservation) stays its own dispatcher under the pipeline; it has no cap/budget/envelope by design, and the sibling family route still dispatches through it with the shared parent as authorizing ancestor.
• Parent and sibling family routes collapse into one sendFamilyTreeMessage core; their envelope/trigger construction moves into AgentPeerMessageBroker.prepareFamilyMessage next to preparePeerMessage, so one module owns every envelope format. Payload/trigger strings are byte-identical to before.
• Budget reservation/refund mechanics are unified (reserveTreeMessageBudget with markPersisted/refundIfUnpersisted) while each route keeps its exact refund policy (refund only when nothing persisted; queued-then-cleared sends keep the charge).
• Peer admission machinery (sender/target liveness, stop-epoch latches, admissionStale probe, dedupe keys, correlation metadata, wake accounting) is preserved unchanged inside the peer leg.
• Duplicated per-route ritual tests (cap, budget refund, workflow refusal, envelope framing) are consolidated into relation-parameterized tests asserting through the public methods; unique-mechanics tests (reactivation, guidance reservation cleanup, stop races, nuclear-family topology) remain separate.

Net: -28 LOC across production and tests (+457/-485).

Validation

• make static-check green; make typecheck green.
• bun test on taskService.test.ts, agentPeerMessageBroker.test.ts, tools/task_list.test.ts, tests/ipc/tasks/persistentSubagentCompaction.test.ts: fail set identical to a clean-base run of the same suite (two pre-existing host-specific fails, no regressions).
• Remote dogfood UAT exercised all four relations end to end on this exact head (descendant steering, inactive-child reactivation, sibling envelope + relationship tags, ancestor turn-end default, 16384-char peer cap refusal, best-of candidate refusal). One High finding surfaced: child-to-root sends that queue behind a busy root turn (queued/turn-end) are never delivered after the turn ends. A controlled re-run of the identical scenario against base main 0672c8f47 reproduced it exactly, so it is a pre-existing defect in the queued-wake drain path, not introduced by this refactor; it deserves a separate fix.

Risks

Intricate-logic refactor in the messaging hot path. Highest-severity regression classes would be: lost or duplicated peer wakes (budget/refund drift), envelope framing changes (security boundary), and descendant reactivation semantics. Mitigations: phase order and refund horizons preserved verbatim per route, envelope strings byte-identical, admission probes untouched, and the relation-parameterized tests assert through the public API with per-route error shapes.

---

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

[ibetitsmike]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: febac31226

ℹ️ 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".

[ibetitsmike]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 3d90822c7c

ℹ️ 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".