agent-mail

<!-- TOC: Boundary | Disciplines | When to Use What | Bootstrap | Reservations | Beads | Troubleshooting | References -->

# Using Agent Mail

> **Core Insight:** Agent Mail is the side channel for leases, notifications, acknowledgements, and handoffs. BR/beads is the durable coordination bus and source of truth for work state, evidence, and decisions.

> **⚠️ TWO SURFACES — read this first.** Every operation has BOTH an MCP-tool form (`send_message`, `fetch_inbox`, …) AND a CLI form (`am mail send`, `am mail inbox`, …). The MCP tools are only present when the agent-mail MCP server is wired into your session's tool surface — **a plain CLI/shell agent (or a session where the MCP server didn't load) will NOT have them.** In that case use the `am` CLI, which works from any shell. **Discoverability trap (br cp-jgcl):** the send/reply verbs live under the `am mail` group, which `am --help` does NOT list, and the read commands have flat aliases (`am inbox`, `am status`) but **`am send` does not exist** — it is **`am mail send`**. When in doubt: `am mail --help`, `am macros --help`, `am file_reservations --help`.

**Don't re-learn the command surface from this skill.** The MCP server self-describes its tools and resources in your tool list; the CLI self-describes via `am --help` and the group helps above. This skill carries only the operating doctrine: when to use mail, the reservation discipline, and the coordination boundaries. Full tool/parameter catalog: [TOOLS.md](references/TOOLS.md).

> **When this applies (scope guard).** Agent Mail coordination — `start-session`, identity registration, file reservations, cross-lane ACKs — is **required when ≥2 lanes/panes share the repo** (a swarm, or you plus a concurrent peer session). With **only one active writer** (no second lane/pane), do **not** register or reserve against yourself — coordination is an escalation, not a session-start tax. If you are the sole writer, skip to the work. (Doctrine: [operating-loop principle 8](../../docs/architecture/operating-loop.md#governing-principles) — single-agent-first.)
>
> **Asymmetry guardrail — the part of the de-mandate that does NOT relax.** AM answers a **contention** axis; ATM answers a separate **durability** axis (they're not a package — full 4-case matrix in [`using-atm`](../using-atm/SKILL.md#when-to-use-atm-vs-am-the-4-case-matrix)). The de-mandate removes the single-writer *session-start tax*, **not** the *collision guard*. The costs are asymmetric: an **unneeded** AM call costs one command; a **missing** one lets two writers silently clobber a shared file and the merge looks like ordinary conflict cleanup while the design forked. So the **`≥2-writers → reserve` reflex stays non-negotiable.** "Trust the models" does not grant two concurrent writers consistency on one path. **Partition before you lock:** if you can cut the write-sets disjoint (sole writer per file), do that instead of reserving — locks are the fallback when partition fails.

## Coordination Boundary

| Need | Source of truth |
|------|-----------------|
| Work queue, status, dependencies, priority, closure evidence | BR/beads (`br`/`bv`) |
| File ownership, active edit leases, lane notifications, acks | Agent Mail |
| Final proof that work is done | Bead notes/closure plus git/CI evidence |
| "Who may write this hot path right now?" | Agent Mail file reservation |

Use Agent Mail to prevent collisions and notify active agents. Do not use it as the durable task queue, audit log, or final evidence store. If a mail thread and BR disagree, reconcile the bead first and link the mail thread from the bead note if the conversation matters.

One-writer-per-hot-dir rule: reserve the path before editing it. If the reservation conflicts, do not write into that path; coordinate with the holder, narrow scope, or wait for the lease to clear.

## Coordination disciplines (2026-06-09, cards 1–5, cp-hhd7)

### Durable lane identities (card 1, cp-9lrb)

Register a **durable adjective+noun identity** at session start. Pane text and
human relay are unauditable and load the operator. The ledger is the bus — both
lanes must be registered to exchange auditable messages. Do not coordinate via
informal pane text when `send_message` + `fetch_inbox` is available.

### Content-push, not pointers (card 2, cp-9lrb)

When sending a lane a message, **push the content** — include the actual text,
diff, or decision. A pointer to a message-id the recipient cannot discover by
inbox is still a relay. If the recipient's inbox is broken and they cannot read
by-id, a pointer is a dead end. Short content fits in the body; long content goes
to a committed artifact with an absolute path, not an AM-internal id.

### Intent on the graph first — dedup (card 3, cp-hhtu)

Before any actor acts on a bead (intake, admit, implement, validate, mutate),
**update the bead status and set the actor on the graph first**, then check for an
existing actor. Parallel pipelines are blind to each other at every tier — dedup
via the ledger, not behavioral coordination. Five exhibits of same-bead parallel
work hit the fleet in one day (impl/validate/admission/mutation/intake, cp-hhtu).
The fix is structural: intent on the graph is the lock.

### ACK-with-id on routed writes (card 5, cp-fmt8)

When routing a write through a single writer (e.g. a beads-intake lane), require
**ACK-with-id** back to the requester — the AM message id of the filed bead or the
`br show <id>` output confirming the record exists. An unacknowledged routed write
is invisible work. "Are these filed?" must not be a question — the ACK closes it.

## When to Use What

| Situation | Action |
|-----------|--------|
| Starting any agent session | `macro_start_session` (CLI: `am macros start-session`) |
| **Confirm a lane actually registered** | `am robot agents --project <abs> --active` — must list your name and each peer lane |
| About to edit files | reserve paths → edit → release reservations |
| Need to tell another agent s