# 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)

```bash
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):
```bash
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

```bash
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.