Orchestrata Ultimate › Plans › research › audit-02-communication-status

Audit 02 — Communication Fabric + Orchestrator Status-Awareness

Source: plans/research/audit-02-communication-status.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-04 · 61 lines.

Prose pending.

Plan text

Audit 02 — Communication Fabric + Orchestrator Status-Awareness

Paths repo-relative. Two runtimes / two registries — the biggest confusion source.

Orientation: two of everything

VolkRegistry collision: kernel/volk_registry.py:398 (rich, heartbeat/health) vs plugin/registries.py:30 (SPEC-015 plugin registry) — unrelated.

CXP protocol

• Real class cxp/_packet_impl.py:544 CXPPacket, flat 11-field + swarm routing + correlation_id/reply_to/tags/metadata.
• Addressing: from_agent/to_agent are free-form literal alias strings — HUMAN, U:Cx, U:BA, U:PM, U:Ux, U:Ar, U:Cd, U:Qa, U:Cp, J:Junior, U:Do, SYSTEM. No address book; alias meaningful only if a key in Postman._handlers.
• Work-status: PENDING→IN_PROGRESS→RESOLVED→ARCHIVED (_packet_enums.py:90/107); WorkTracker is packet-scoped not volk-scoped.
• Delivery: QUEUED→DELIVERED→ACKNOWLEDGED/FAILED.
• PacketType.HEARTBEAT exists (_packet_enums.py:30) + priority-mapped, but never constructed/sent.

Dispatch (live path = Postman, NOT kernel/dispatcher.py)

• Register: kernel/pipeline.py:116-143 _register_volks → postman.register(alias, volk.process); volk.set_postman.
• Route: postman/sync_router.py:55 route_sync → persists Redis cxp:thread:{tid} → _route_sync_deliver:86 looks up _handlers[to_agent]. Unknown alias → left QUEUED, returns None.
• In-process: orchestrator/pipeline_kernel.py:91 send_packet only accepts to_agent=="U:Cx" && subject=="intent" → orchestrator/pipeline_runner.py:122 run → PipelineRouter.route (pipeline_router.py:195) stage list → each via Postman.route_sync.
• Intent order: orchestrator/pipeline_router.py:86 WORK_TYPE_CAPABILITIES[FEATURE]; gRPC path uses escalation_target + kernel/pipeline.py:406 _RESUME_ORDER.

Volk↔volk: NO arbitrary messaging (fixed choreography)

• Hardcoded next hop escalation_target: Cx→dyn/None; BA→U:PM (analyst/agent.py:47); PM→U:Ar (pm/volk.py:172); Ux→U:Ar (ux/volk.py:89); Ar→U:Cd (architect/volk.py:50); Cd→U:Qa (codedirector/volk.py:60); Do→U:Cp (documentor/volk.py:45); Cp→None.
• process() returns exactly ONE packet (HUMAN or escalation target). Loop pipeline_escalation.py:36 _route_escalation routes while to_agent in self.volks.
• Transport CAN address any registered alias — missing is the intent + a resolver, and the ability to side-message while continuing work (single return, sync escalation).
• Latent BaseAgent.send() (agents/volks/base.py:89) → Postman.aroute works, but only caller is emit_event() → targets SYSTEM (no handler = no-op).
• Buses kernel/event_bus.py, kernel/pipeline_events.py::PipelineEventBus carry telemetry, not addressable messages.

Orchestrator status: NO live query

1. Live per-volk status real but CLI-only: agents/volks/base.py:47-49 (status/summary/current_thread); kernel/pipeline.py:321 get_status() → only consumer kernel/pipeline_cli.py:140. Not over gRPC/gateway.
2. Gateway volk.list/volk.get = static configs/volks.yaml/_DEFAULT_VOLK_REGISTRY (gateway/handlers/volk.py:21,233); hardcodes health/current_task. Roster aliases (U:Ox/U:PS/U:Vz/U:KR) don't even match live aliases.
3. cxp.status (gateway/handlers/cxp.py:379) = packet delivery status per thread, not volk liveness.
4. Rich registry orphaned: kernel/volk_registry.py has VolkStatus/VolkHealth/last_heartbeat/record_heartbeat(:1032)/get_volk_health(:987)/in_flight/query_volks(:1100) — but not instantiated by either live runner; record_heartbeat has ZERO call sites.
5. PacketType.HEARTBEAT never emitted. Gateway heartbeat = WS UI↔gateway ping, unrelated.

Reply transport

• gRPC: cxp/grpc_server.py:154 send_packet unary → CXPReceipt ack; reply pushed to single global _packet_queue (:145); drained by streaming receive_packet (:242, ignores agent_id). Gateway server.py:426 _consume_kernel_replies → receive_packets("HUMAN") → broadcast("cxp.traffic", reply).
• In-process fallback: pipeline_kernel.py:199 _emit_event → injected broadcast("pipeline.{tid}") or Redis xadd pipeline:events → gateway/server.py:460 _consume_pipeline_events. Two non-uniform reply channels (cxp.traffic vs pipeline.).

Insertion points

Volk↔volk

• G1 route multiple/targeted outbound in pipeline_escalation.py:36 _route_escalation / _next_escalation_target:135 / _route_one_hop:120 (accept a list / fan-out queue).
• G2 let volks call self.send() mid-process to a resolved recipient; need capability→alias resolver (kernel/volk_registry.py:751 list_volks_by_capability).
• G3 real mailboxes: per-alias Redis queues (postman:q:{id}) exist but volks never dequeue (postman/postman.py:286).
• G4 register each volk into a shared VolkRegistry at kernel/pipeline.py:139-143 for peer discovery.

Status

• G5 expose get_status() via subject=="status" in agents/kernel_handler.py:81 or a kernel.status RPC in gateway/rpc.py:293.
• G6 replace static roster: inject kernel client into VolkHandler (mirror handlers/orchestrator.py:38 set_kernel_client), populate from G5.
• G7 feed the orphaned registry: instantiate VolkRegistry in kernel/pipeline.py:__init__, record_heartbeat(alias) at dispatch boundary (sync_router.py:220 _dispatch_sync / pipeline_escalation.py:120), bump in-flight.
• G8 emit volk.status event on every WorkStatus transition, forward like pipeline events (kernel/pipeline_events.py → gateway/server.py:460).
• G9 actually send PacketType.HEARTBEAT (interval agents/constants.py:38 DEFAULT_HEARTBEAT_INTERVAL_SECONDS=30.0).
• G10 per-conversation reply demux: key _packet_queue by agent_id/thread_id.

Highest-leverage

Primitives exist (alias addressing, Postman dispatch to any alias, send(), WorkStatus, get_status(), heartbeat/health registry). Work = wiring: (1) route arbitrary/multiple recipients in _route_escalation backed by a live VolkRegistry capability resolver; (2) feed record_heartbeat/in-flight at sync_router._dispatch_sync + expose get_status()/get_volk_health via a kernel.status RPC replacing the static roster.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks