# How HiveManager Coordinates Inter-Agent Messaging with Mailboxes and Single-Committer Git

> Discover how HiveManager ensures reliable inter-agent messaging with mailboxes and a single-committer Git repo. Learn about crash-resilient delivery and auditability.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: architecture
- Published: 2026-08-29

---

**HiveManager enables deterministic, crash-resilient message delivery between agents using atomic file renames across per-agent mailboxes, coupled with a single-committer Git repository that only the main process writes to, eliminating race conditions while maintaining full auditability.**

The **HiveManager** class serves as the core coordination engine in the *Munder Difflin* multi-agent harness, providing a file-based messaging fabric that keeps agents completely unaware of version-control mechanics. By combining per-agent inboxes and outboxes with a strictly controlled Git commit strategy, the system guarantees exactly-once delivery semantics without exposing agents to "index.lock" conflicts or repository maintenance tasks.

## Per-Agent Mailbox Architecture

Every agent registered with the harness receives dedicated storage directories under `<hive>/agents/<agentId>/`. Specifically, each agent gets an `inbox/` for incoming messages and an `outbox/` for outgoing traffic.

The TypeScript interfaces defining the message structure and mailbox locations reside in [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts). The `HiveMessage` type models the protocol format, while `VoiceMessage` handles the UI-facing representation that tracks `direction` and `owner` attributes (see lines 56–92). This separation ensures that the internal routing logic operates on strict types while the presentation layer receives metadata-rich objects suitable for display.

## Atomic Message Routing with routerTimer

The `HiveManager` runs a periodic `routerTimer` that scans each agent’s `outbox/` directory and drains messages to their destinations. This process relies on **atomic file system operations** to guarantee exactly-once delivery even if the application crashes mid-transfer.

According to the implementation comments at the top of the class (lines 5–12), the router performs the following sequence:

```typescript
// Pattern extracted from src/main/hive.ts router implementation
for (const agentId of this.registry().agents) {
  const outbox = join(this.agentDir(agentId), 'outbox');
  for (const file of readdirSync(outbox)) {
    const msg = readFileSync(join(outbox, file), 'utf8');
    const { to } = JSON.parse(msg) as HiveMessage;
    const inbox = join(this.agentDir(to), 'inbox');
    // Atomic move guarantees delivery exactly once
    renameSync(join(outbox, file), join(inbox, file));
  }
}
// Record state change in Git
this.commit('hive: router drain');

```

The critical operation is `renameSync`, which atomically moves the message file from the sender’s `outbox/` to the recipient’s `inbox/`. Because POSIX renames are atomic, a crash occurring during the operation leaves the message either in the source location (pending retry) or the destination (successfully delivered), never in a corrupted or duplicated state.

## Single-Committer Git Design

Unlike distributed Git workflows where multiple writers contend for the repository, **Munder Difflin enforces a single-committer model** where only the main HiveManager process commits to the repository. The entire hive lives under `<harnessHome>/hive/`, initialized as a dedicated Git repository during bootstrap (lines 84–88).

After the router completes its drain cycle, `HiveManager` calls `this.commit('hive: …')` to snapshot the new mailbox states (e.g., lines 102–103). Because no agent ever invokes Git commands directly, the design eliminates "index.lock" race conditions and ensures a linear, clean commit history that reflects the exact sequence of message deliveries.

This architecture provides three operational advantages:

- **No repository contention** – Agents write only to their `outbox/` directories using standard file I/O, never triggering Git locks.
- **Deterministic replay** – Each commit represents a consistent global state of all mailboxes, enabling trivial debugging and state reconstruction.
- **Simplified backup** – Standard Git tooling (`git log`, `git diff`, `git checkout`) can inspect, back up, or roll back the entire message history.

## Message Security and Lifecycle

Before any message crosses IPC boundaries to the UI or voice layers, `HiveManager` invokes `redactSecrets` (implemented in lines 62–89 of [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts)) to strip credential-like strings from the payload. The sanitized result is then wrapped in a `VoiceMessage` object that exposes only the necessary metadata to external consumers.

This workflow ensures that sensitive authentication tokens or API keys never leave the main process, while still allowing the UI to display message flow and ownership information through the `direction` and `owner` fields.

## Bootstrap and Durability

The `ensureHive()` function (lines 26–34) establishes the entire coordination environment. It creates the directory structure, generates a [`PROTOCOL.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/PROTOCOL.md) specification file, initializes the Git repository if absent, and writes the bundled-node launcher that shim scripts use to communicate with the harness.

Because the hive is a standard Git repository, operators can use conventional version-control workflows to audit agent conversations. The [`src/main/fs.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/fs.ts) module provides path expansion utilities like `expandTilde` used when constructing mailbox paths, while [`src/main/usage.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/usage.ts) maintains the cost ledger that the router updates after each commit. Provider-specific shims in [`src/main/agentProvider.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/agentProvider.ts) (along with `hive-proxy.cjs` and `cth-hook.cjs`) translate external hook payloads into the generic `HiveMessage` format written to agent outboxes.

## Summary

- **Atomic file renames** between outbox and inbox directories provide exactly-once delivery semantics without message brokers or databases.
- **Single-committer Git model** prevents index.lock races by restricting all repository writes to the main HiveManager process, producing linear, auditable history.
- **Automatic secret redaction** via `redactSecrets` ensures credentials never cross IPC boundaries, while `VoiceMessage` types safely expose routing metadata to UI layers.
- **File-based durability** means the message log is a standard Git repository at `<harnessHome>/hive/`, compatible with native Git tooling for inspection and rollback.

## Frequently Asked Questions

### How does HiveManager prevent message loss during a system crash?

The system relies on **atomic `renameSync` operations** when moving files from an agent’s `outbox/` to the recipient’s `inbox/`. Because POSIX file renames are atomic with respect to crashes, a message either remains in the sender’s outbox (to be retried by the `routerTimer` after restart) or appears completely in the receiver’s inbox. The subsequent Git commit only occurs after all renames complete successfully, ensuring the repository state always reflects successfully delivered messages.

### Why does HiveManager restrict Git commits to a single process instead of letting agents commit directly?

Restricting commits to the main HiveManager process **eliminates repository contention** and "index.lock" conflicts that would occur if multiple agents attempted concurrent writes. This single-committer design guarantees a linear commit history, simplifies crash recovery, and allows agents to remain lightweight processes that perform only standard file I/O to their mailboxes without linking Git libraries or executing shell commands.

### How does the system protect sensitive credentials in inter-agent messages?

Before a message leaves the main process, the `redactSecrets` function (lines 62–89 in [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts)) scans the payload and removes credential-like strings. The cleaned data is then wrapped in a `VoiceMessage` object that exposes only non-sensitive metadata such as `direction` and `owner` to the UI and voice layers. This ensures that API keys and authentication tokens never traverse IPC boundaries or appear in the Git-tracked message log.

### Can operators use standard Git tools to inspect the message history?

Yes. The `ensureHive()` function initializes a standard Git repository at `<harnessHome>/hive/`. Because HiveManager commits atomically after each router cycle, the Git history contains a complete, time-ordered snapshot of all mailbox states. Operators can use `git log`, `git diff`, or `git checkout` to audit agent conversations, debug message flows, or roll back the harness to previous states.