siloqy/prod/docs/H5I_MESSAGING_SETUP.md

h5i — Cross-Agent Messaging (AUTHORITATIVE — read this to connect)

This is THE single source of truth for agent comms. If anything elsewhere conflicts, this wins. Last updated 2026-06-22 by claude (integrator) to fix a bus split that left agents unable to see each other's messages.

---

0. TL;DR — how to be reachable (do this first)

cd /mnt/dolphinng5_predict          # ← THE CANONICAL BUS lives here. Always run h5i from here.
export H5I_AGENT=<your-handle>      # e.g. codex / cmd-PASS9 / cmd-pass6 / cmd-pass5 / claude
h5i msg inbox                       # read + mark your unread

Rule: always operate h5i with cwd = /mnt/dolphinng5_predict. That checkout's refs/h5i/msg is the ONE canonical bus everyone shares. Do not send/read from a fork clone — that's what split us.

---

1. Why we split (so it doesn't happen again)

refs/h5i/msg is per-clone. We had two diverged copies:

• CANONICAL: /mnt/dolphinng5_predict refs/h5i/msg (also mirrored read-only at /mnt/vp-oa4).
• FORK: /mnt/vp-PASS9 refs/h5i/msg — where PASS9 had been reading/writing.

They never reconciled because h5i share push targets the Gitea origin (…/siloqy.git), which HANGS (broken server-side hook). So claude's messages (on canonical) never reached PASS9 (on the fork), and vice-versa. Do not rely on share-to-Gitea.

2. The fix — converge on the canonical bus

Everyone reads/writes the canonical bus by running h5i from /mnt/dolphinng5_predict. That path is the shared checkout all agents can reach; one ref, no push/pull, no divergence.

If you are forced to work inside a fork clone (e.g. /mnt/vp-PASS9, whose git origin is the LOCAL path /mnt/dolphinng5_predict), sync the bus locally (this does NOT touch Gitea, so it works):

cd /mnt/vp-PASS9
h5i share pull      # pulls h5i refs from your local origin (/mnt/dolphinng5_predict)
# … work, send …
h5i share push      # pushes back to the LOCAL origin (fine). NEVER push to the Gitea remote.

But the simpler, recommended path is just: don't — run h5i from /mnt/dolphinng5_predict directly.

3. Identities (current)

Handle	Role	Current PASS2 task
claude	Integrator (owns merges to main, bit-verification)	—
codex	Parity / V3.4b live-factor / HZ	PASS2.5 conviction soak
cmd-PASS9	ASEx kernel / race-safety	PASS2.2 arming-gate, PASS2.6 HZ client
cmd-pass6	Execution internals (OrderFSM/FillPump/Reconciler)	PASS2.3 VST adapter, PASS2.4 wiring
cmd-pass5	Mock-BingX adapter	PASS2.1 VST creds + isolation
aider_nvnemo	Aider assistant (this session)	PASS2.x ad-hoc support

Set yours: export H5I_AGENT=<handle> (or h5i msg as <handle>).

4. Usage

h5i msg                       # inbox dashboard (glance)
h5i msg inbox                 # show unread, mark read (numbers them)
h5i msg send <recipient> "…"  # free-text ( 'all' = broadcast )
h5i msg ask <recipient> "…"   # a request expecting a reply
h5i msg reply <n> "…"         # threaded reply to message #n
h5i msg ack|done|decline <n> "…"
h5i msg wait --timeout 600    # block until a reply arrives (run as a background waiter)
git show refs/h5i/msg:messages.jsonl   # raw view

Types: ASK · REVIEW_REQUEST · RISK · HANDOFF · BROADCAST · ACK · DONE.

5. Code workflow (so comms + code don't re-split) — see VIOLET_PASS2_SERIES_INDEX.md

• Single trunk: /root/violet main on local disk; shared bare origin /root/violet.git (NOT Gitea). Your PASS2 worktree is /root/violet-wt/pass2.<n>-<slug> on branch agent/pass2.<n>-<slug>. Work there, push to /root/violet.git. Do not branch from /mnt CIFS clones.
• Sub-specs: prod/docs/VIOLET_PASS2.<n>_*.md (also replicated to /mnt/dolphinng5_predict/prod/docs/).
• Commit hygiene: explicit staging (never git add .), Co-Authored-By: trailer, tests in-commit.

6. De-confliction note

This file supersedes the comms sections of VIOLET_CMD_ONBOARDING__PASS5.md and any per-pass spec — those defer here for how to connect. Operator points all agents at THIS file.