# Co-op Mode Protocol

## Roles

- **Initiator** = whoever starts the task (agent or human). Owns decisions and receives updates.
- **Leader/Coordinator** = coordinates phases, merges, and final decisions (often the initiator).
- **Worker** = executes assigned phases and reports back to the initiator.

**Default pairing note**: Claude is often faster and more decisive, while Codex tends to be deeper but slower. That commonly makes Claude a natural coordinator and Codex a strong worker. This is a default, not a rule — roles are set per task by the initiator. Grok CLI can join as an additional optional peer/worker (e.g. a third `amq coop exec grok` in a three-way session) without changing this default two-engine pairing note.

## Phased Flow

| Phase | Mode | Description |
|-------|------|-------------|
| **Research** | Parallel | Both explore codebase, read docs, search. No conflicts. |
| **Design** | Parallel -> Merge | Both propose approaches. Leader merges/decides. |
| **Code** | Split | Divide by file/module. Never edit same file. |
| **Review** | Parallel | Both review each other's code. Leader decides disputes. |
| **Test** | Parallel | Both run tests, report results to leader. |

```
Research (parallel) -> sync findings
    v
Design (parallel) -> leader merges approach
    v
Code (split: divide files/modules)
    v
Review (parallel: each reviews other's code)
    v
Test (parallel: both run tests)
    v
Leader prepares commit -> user approves -> push
```

## Key Rules

1. **Initiator rule** — reply to the initiator and ask the initiator for clarifications
2. **Never branch** — always work on same branch (joined work)
3. **Code phase = split** — divide files/modules to avoid conflicts
4. **File overlap** — if same file unavoidable, assign one owner; other reviews/proposes via message
5. **Coordinate between phases** — sync before moving to next phase
6. **Leader decides** — initiator or designated leader makes final calls

## Stay in Sync

- After completing a phase, report to the initiator and await next assignment
- While waiting, safe to do: review partner's work, run tests, read docs
- If no assignment comes, ask the initiator (not a third party) for next task

## Progress Protocol (Start / Heartbeat / Done)

- **Start**: send `kind=status` with an ETA to the initiator as soon as you begin.
- **Heartbeat**: update on phase boundaries or every 10-15 minutes.
- **Done**: send Summary / Changes / Tests / Notes to the initiator.
- **Blocked**: send `kind=question` to the initiator with options and a recommendation.

## Modes of Collaboration (Modus Operandi)

- **Leader + Worker**: leader decides, worker executes; best default.
- **Co-workers**: peers decide together; if no consensus, ask the initiator.
- **Duplicate**: independent solutions or reviews; initiator merges results.
- **Driver + Navigator**: driver codes, navigator reviews/tests and can interrupt.
- **Spec + Implementer**: one writes spec/tests, the other implements.
- **Reviewer + Implementer**: one codes, the other focuses on review and risk detection.

## Communication

- Use AMQ messages to coordinate between phases and report to the initiator
- Don't paste code blocks — reference file paths (shared workspace)

## Interrupts

- Urgent messages labeled `interrupt` trigger an interrupt notice when wake is
  running. The label never enables Ctrl+C by itself; real SIGINT requires the
  explicit destructive opt-in `--interrupt-cmd ctrl-c`.
- Input injection can activate a focused permission or approval dialog. Payload
  text alone may match single-key shortcuts, so removing Enter is not safe.
- `--defer-while-input` reduces collisions with recent typing but cannot detect
  modal state; an idle dialog looks like an idle composer.
- For an AMQ-enforced zero-input watcher, run `amq wake --inject-mode none` or
  `amq coop exec --require-wake --wake-inject-mode none <agent>`. This mode
  writes notices to wake stderr, turns urgent interrupts into one bell plus the
  output notice, and rejects `--inject-via`, `--inject-arg`, and `--inject-cmd`.
  Stderr shares the TUI terminal by default and may remain visible until redraw.
- When starting a new wake after the agent owns its terminal, pass `amq wake
  --baseline-existing ...`. Existing `inbox/new` messages remain unread and
  emit no receipts; only later arrivals trigger that fresh wake. `coop exec`
  adds the flag to wakes it starts. `wake repair` instead inherits the dead
  generation's private device/inode/ctime suppression floor; it does not
  re-snapshot `inbox/new`, so messages delivered during notifier downtime
  remain eligible. Reuse requires generation-bound proof that the live wake
  completed watcher preparation. It does not retroactively baseline that wake,
  so pending backlog can still notify; SessionStart draining mitigates that
  residual.

## Message Handling

- `amq drain --include-body` — process incoming messages
- `amq send --to <partner>` — send work/findings to partner
- `amq send --to <partner> --wait-for drained --wait-timeout 60s` — block on a single-recipient handoff
- `amq receipts list --me <agent> --msg-id <msg_id>` — inspect delivery history
- `amq receipts wait --me <agent> --msg-id <msg_id> --stage drained` — wait for receipt arrival
- `amq reply --id <msg_id>` — reply in thread

`amq read`, `amq drain`, and `amq monitor` all strict-validate headers before treating a message as successfully ingested. If a message in `inbox/new` is corrupt or malformed, AMQ moves it to DLQ and emits a `dlq` receipt instead of leaving it in place.

## Spec Workflow

The spec workflow is a skill-managed protocol that uses standard AMQ kinds plus labels (`workflow:spec`, `phase:*`) on thread `spec/<topic>`.

Canonical spec phases are:
`Research -> Discuss -> Draft -> Review -> Present -> Execute`

For the full spec protocol, see the amq-spec skill's `spec-workflow.md`.

# Cross-Project Messaging

Send messages between agents in different projects. Requires peer configuration in `.amqrc`.

## Peer Configuration

Each project's `.amqrc` maps peer names to their base root paths:

```json
{
  "root": ".agent-mail",
  "project": "proj-a",
  "peers": {
    "proj-b": "/Users/me/projects/proj-b/.agent-mail"
  }
}
```

- `project`: explicit self-identity (defaults to directory basename if absent)
- `peers`: name → absolute path to peer's base root

**Critical naming rule**: Peer keys must match the remote project's declared `project` name (or its directory basename if `project` is absent). Reply routing uses `reply_project` which is set to the sender's project identity — the receiver must have a peer entry with that exact name. If project A calls its peer `backend` but that project identifies as `api-server`, replies from `api-server` will fail because A has no peer named `api-server`.

Both projects must register each other as peers for round-trip messaging.

## Addressing

### Flag syntax (explicit)
```bash
amq send --to codex --project proj-b --body "hello"
amq send --to codex --project proj-b --session auth --body "to specific session"
```

### Inline syntax (terser)
```bash
amq send --to codex@proj-b --body "hello"
amq send --to codex@proj-b:auth --body "to specific session"
```

Flags take precedence over inline syntax.

## Same-Handle Messages

A matching sender and recipient handle has three distinct meanings:

| Route | Meaning |
|---|---|
| `--project` is present | A different agent instance in another project. AMQ stamps `from_project` and reply routing metadata. |
| `--session` or `--from-session` is present | A different agent instance in another session. AMQ stamps session reply routing metadata. |
| No routing dimension is present | A same-root self-send with no provenance beyond the handle. `amq send` refuses it by default. |

Use `--allow-self` only to confirm an intentional same-root self-send. The flag
does not make `--root` a routing dimension, add reply metadata, or bypass the
cross-tree and session-pin guards. To reach another instance of your handle,
use `--project` or `--session` instead; routed same-handle sends do not require
`--allow-self`.

## Session Defaults

`--project proj-b` without `--session` delivers to the **same session name** in the peer project. If your source root is `.agent-mail/collab`, the message goes to `proj-b's .agent-mail/collab`. Override with explicit `--session`.

## Reply Routing

Cross-project messages carry `reply_to` (handle@session) and `reply_project` (project name). When you receive a cross-project message:

```bash
amq reply --id <msg_id> --body "got it"
```

The CLI reads `reply_project` from the message, resolves the peer, and delivers to the correct project/session. The reply re-stamps `reply_to` and `reply_project` with the replier's own identity for continued round-trip.

## Thread Naming

- **Same project P2P**: `p2p/claude__codex`
- **Cross-session P2P**: `p2p/collab:claude__auth:codex`
- **Cross-project P2P**: `p2p/proj-a:collab:claude__proj-b:collab:codex`
- **Topical threads**: Use the same thread ID across all participating projects (e.g., `decision/api-v2`, `review/auth-module`)

## Safety

- `DeliverToExistingInbox`: Cross-project delivery **never creates directories** in the peer project. The target inbox must already exist (created by `amq init` or `amq coop init` in the peer project). This prevents accidental scaffolding.
- Peer paths must be absolute (or relative to `.amqrc` directory).
- `resolvePeer` validates the path exists before delivery.

## Decision Threads

Decentralized decision protocol for cross-project coordination, based on RFC 7282 rough consensus. Uses existing AMQ primitives — no new CLI commands.

### Process

1. **Propose**: Send a `decision` kind message on thread `decision/<topic>` with label `decision:proposal`
2. **Review/Object**: Participants reply with `decision:support` or `decision:objection` labels. Add `blocking` label for unresolved objections.
3. **Resolve**: Address blocking objections. Running code (tests) is stronger evidence than arguments.
4. **Close**: When all required projects have responded and no unresolved blocking objections remain, send `decision:final`.

### Convention

```bash
# Proposal
amq send --to codex --project proj-b --kind decision \
  --labels "decision:proposal,project:proj-a,project:proj-b" \
  --thread "decision/api-v2" \
  --context '{"proposal_id":"api-v2","question":"Adopt new API?","required_projects":["proj-a","proj-b"],"deadline":"2026-03-25"}' \
  --body "Proposal: migrate to API v2. All tests green."

# Support
amq reply --id <msg_id> --kind decision \
  --labels "decision:support" \
  --body "LGTM. Tests pass on our side."

# Objection
amq reply --id <msg_id> --kind decision \
  --labels "decision:objection,blocking" \
  --body "Breaks backward compat for our consumers."

# Final decision
amq reply --id <msg_id> --kind decision \
  --labels "decision:final" \
  --body "Adopted with backward-compat shim. Shipping in v0.25."
```

### Context schema for proposals

```json
{
  "proposal_id": "api-v2",
  "question": "Should we adopt the new API?",
  "options": ["adopt", "defer", "reject"],
  "required_projects": ["proj-a", "proj-b"],
  "deadline": "2026-03-25",
  "evidence": ["All CI green", "perf benchmarks attached"]
}
```

## What NOT to use cross-project for

- **Same project, different session**: Use `--session` instead
- **Swarm mode**: Agent teams are project-scoped. Use AMQ bridge for swarm notifications within a project.
- **Broadcasting**: No `--to @all` across projects. Send individually to each peer.

# Orchestrator Integrations

Use these commands when AMQ is the messaging layer underneath an external orchestrator.

AMQ's core transport is still the **message**. These adapters are intentionally narrow: they translate external lifecycle or task events into ordinary AMQ messages.

## Root Resolution

For orchestrator-spawned agents, make the queue discoverable even when the
process starts outside an AMQ-enabled repo. Global settings are fallbacks and
do not shadow a project-local config:

```bash
export AMQ_GLOBAL_ROOT="$HOME/.agent-mail"
```

Or create `~/.amqrc`:

```json
{"root": ".agent-mail"}
```

Root precedence:

```text
explicit --root > AM_ROOT > project-local .amqrc > AMQ_GLOBAL_ROOT > conditional implicit fallbacks
```

Inside a Git worktree or bare repository, the only implicit fallback is the
repository-local detected `.agent-mail`; an implicit `~/.amqrc` is ineligible.
Outside Git, `~/.amqrc` precedes eligible local `.agent-mail` detection.
Auto-detection covers `.agent-mail/<session>` session roots without `.amqrc`.
Custom root names still need `.amqrc`, explicit flags, or environment variables.

If an orchestrator leaves the terminal pinned to another root while cwd has an
initialized local queue, implicit participating commands refuse rather than
silently using the pin. Repin to the cwd-local queue, route deliberately with
`--session`/`--project`, or pass an explicit `--root` to confirm the active
queue; ordinary pin checks still apply.

## Symphony

Lightweight optional hook adapter.

Patch `WORKFLOW.md` once:

```bash
amq integration symphony init --me codex
amq integration symphony init --me codex --check
```

Emit lifecycle events from hooks:

```bash
amq integration symphony emit --event after_create --me codex
amq integration symphony emit --event before_run --me codex
amq integration symphony emit --event after_run --me codex
amq integration symphony emit --event before_remove --me codex
```

Known limitation: `init` rewrites `WORKFLOW.md` through structured YAML/Markdown parsing, so frontmatter comments and formatting may be normalized.

## Cline Kanban

Experimental bridge. Run it only if you are comfortable depending on a fast-moving preview WebSocket surface:

```bash
amq integration kanban bridge --me codex
amq integration kanban bridge --me codex --workspace-id my-workspace
```

Defaults:

- URL: `ws://127.0.0.1:3484/api/runtime/ws`
- Reconnect delay: `3s`
- Emits only on task session state transitions plus `task_ready_for_review`

## Runtime Diagnostics

```bash
amq doctor --ops
amq doctor --ops --json
amq doctor --root <exact-root> --ops
```

`doctor --ops` adds queue depth, sibling-session backlog hints, oldest unread
age, DLQ state, presence freshness, and integration hints on top of the base
`doctor` checks. A `sibling_backlog` hint includes an exact non-destructive
`amq list --session <name> --me <handle> --new` inspection command.

An explicit doctor root selects the inspected tree without changing the
terminal pin. Inspection continues with a mismatch warning. Mutating doctor
operations (`--fix-mailboxes` or `--ops --fix-wake-locks`) require the target
to match the pin unless the command uses an explicit non-empty `--root`
together with `--ignore-session-pin`. `--base-root` supplies config authority
for the target or one direct child and never waives the pin.

## Message Shape

Integration messages are self-delivered and carry metadata under `context.orchestrator`:

```json
{
  "orchestrator": {
    "version": 1,
    "name": "kanban",
    "transport": "bridge",
    "event": "task_ready_for_review",
    "workspace": {
      "id": "workspace-123",
      "path": "/abs/path/to/worktree"
    },
    "task": {
      "id": "task-42",
      "prompt": "Review PR #47",
      "column": "review",
      "state": "awaiting_review",
      "review_reason": "task_ready_for_review",
      "agent_id": "codex"
    }
  }
}
```

Common labels:

- `orchestrator`
- `orchestrator:symphony` or `orchestrator:kanban`
- `task-state:<state>`
- `handoff`
- `blocking`

For the formal envelope and stability notes, see [`docs/adapter-contract.md`](../../../docs/adapter-contract.md).

# Message Format Cheatsheet

AMQ messages are Markdown files with a JSON frontmatter header:

```text
---json
{
  "schema": 1,
  "id": "<msg_id>",
  "from": "claude",
  "to": ["codex"],
  "thread": "p2p/claude__codex",
  "subject": "Optional summary",
  "created": "<RFC3339 timestamp>",
  "refs": ["<related_msg_id>"],

  "priority": "normal",
  "kind": "question",
  "labels": ["bug", "parser"],
  "context": {"paths": ["internal/cli/send.go"], "focus": "error handling"},

  "reply_to": "claude@collab",
  "reply_project": "my-project",
  "from_project": "my-project"
}
---
<markdown body>
```

Field notes:
- `schema`: integer schema version (currently 1).
- `id`: globally unique message id (also the filename stem on disk).
- `from`: sender handle.
- `to`: list of receiver handles.
- `thread`: thread id string. For p2p, use `p2p/<a>__<b>` with lexicographic ordering.
- `subject`: optional short summary.
- `created`: RFC3339 timestamp.
- `refs`: optional list of related message ids (e.g., replies).
- `priority`: optional (`urgent`, `normal`, `low`).
- `kind`: optional (e.g., `review_request`, `review_response`, `question`, `answer`, `status`, `todo`).
- `labels`: optional list of tags for filtering.
- `context`: optional JSON object for structured metadata.

Routing fields (set automatically by CLI — do not hand-craft):
- `reply_to`: optional sender identity for routing replies (e.g., `claude@collab`). Set on cross-session and cross-project sends.
- `reply_project`: optional sender project name for cross-project reply routing (e.g., `my-project`). Present only on cross-project messages.
- `from_project`: optional sender project identity stamped on cross-project sends.

Notes:
- Don’t edit message files directly; use the CLI.
- On macOS and Linux, publication into `inbox/new` is a no-replace rename: a
  colliding name keeps the existing file and the new attempt, rather than
  overwriting. Readers still scan only `new` and `cur`.
- The CLI auto-fills `id`, `created`, and a default `thread` when not provided.
- `reply_to`, `reply_project`, and `from_project` are transport metadata stamped by the CLI.
- Delivery outcomes are tracked separately in consumer-local receipt files. `drained` means the consumer ingested the message; `dlq` means ingest failed and the message moved to DLQ.

## Integration Metadata

Messages emitted by `amq integration ...` commands store orchestrator-specific metadata under `context.orchestrator`.

Example:

```json
{
  "labels": ["orchestrator", "orchestrator:kanban", "task-state:awaiting_review", "handoff"],
  "context": {
    "orchestrator": {
      "version": 1,
      "name": "kanban",
      "transport": "bridge",
      "event": "task_ready_for_review",
      "workspace": {
        "id": "workspace-123",
        "path": "/abs/path/to/worktree"
      },
      "task": {
        "id": "task-42",
        "prompt": "Review PR #47",
        "column": "review",
        "state": "awaiting_review"
      }
    }
  }
}
```

Label conventions:

- Always: `orchestrator`, `orchestrator:<name>`
- When state is known: `task-state:<state>`
- Review-ready handoffs: `handoff`
- Failed / interrupted work: `blocking`

# AMQ CLI Skill

File-based message queue for agent-to-agent coordination.

AMQ manages the conversation, not the task plan. Use it for messaging, routing, replies, and adapter-emitted lifecycle events; keep work decomposition and execution in the orchestrator above it.

## Prerequisites

Requires `amq` binary in PATH. Install:
```bash
curl -fsSL https://raw.githubusercontent.com/avivsinai/agent-message-queue/main/scripts/install.sh | bash
```

### Native Windows submitted injection

The native Windows core queue works, and the separately published
`amq-keepalive.exe` can submit to an exact live Codex or Claude Code session:

```powershell
amq-keepalive.exe inject codex-queue "codex-queue:thread:$env:CODEX_THREAD_ID" "check the AMQ inbox"
amq-keepalive.exe inject claude-print "claude-print:session:<uuid>" "check the AMQ inbox"
```

Do not translate this into `amq wake` or `coop exec`: native Windows does not
provide their Unix terminal lifecycle. `codex-queue` also requires an active
writer for the exact thread; an idle lock file is not sufficient.

## Environment Rules

AMQ primarily uses `AM_ROOT` (which mailbox tree) and `AM_ME` (which agent).
Pinned terminals also carry `AM_BASE_ROOT` plus an independent `AM_SESSION`
identity; sessionless pins use the exact root as `AM_BASE_ROOT` and an empty
`AM_SESSION`. Getting these wrong means messages go to the wrong place or
silently disappear, so let the CLI handle them rather than guessing.

**Inside `coop exec`** — everything is pre-configured. Just run bare commands:
```bash
amq send --to codex --body "hello"     # correct
amq send --me claude --to codex ...    # wrong — --me overrides the env
./amq send ...                         # wrong — use amq from PATH
```
The reason: `coop exec` sets `AM_ROOT`, `AM_ME`, `AM_BASE_ROOT`, and
`AM_SESSION` precisely for the session. Passing `--me` overrides the identity;
for read-side sibling access, use `--session <name>` instead of overriding the
raw root.

**Outside `coop exec`** — resolve the root from config, don't hardcode it:
```bash
amq_context="$(amq env --me claude)" && eval "$amq_context"  # reads .amqrc chain, replaces the full context
amq_context="$(amq env --session auth --me claude --export)" && eval "$amq_context"  # pin one session

# Or use an isolated subshell without polluting the parent shell:
(
  amq_context="$(amq env --me claude)" &&
  eval "$amq_context" &&
  amq send --to codex --body "hello"
)
```
Why not hardcode? The root path depends on project and explicit configuration,
then context-sensitive implicit fallbacks. Hardcoding skips this and breaks
when the project moves or config changes.
Every shell-mode `amq env` invocation replaces the complete context. It emits
`AM_SESSION` unconditionally (empty for a sessionless root), exports
`AM_BASE_ROOT` as the authorized parent for named sessions or the exact root for
a sessionless context.
`--export` additionally prints a stderr pin note. Treat the evaluated output as
one terminal, one session.

**Global fallback**: Orchestrator-spawned agents often start outside an
AMQ-enabled repo where no project `.amqrc` or repo-local `.agent-mail` exists.
Set `AMQ_GLOBAL_ROOT` or `~/.amqrc` so `amq env` and `amq doctor` still resolve
the correct queue. `AMQ_GLOBAL_ROOT` is explicit authority and therefore
precedes repo-local auto-detection. The implicit home config is ineligible
inside a Git worktree or bare repository.
A Git worktree or bare repository with no eligible root refuses implicit
`~/.amqrc` fallback because it can silently select another project's mailbox.
Participating commands keep that refusal. `coop exec` honors root precedence,
then bootstraps a worktree-local queue at the Git top when no eligible root
exists; `coop exec --no-init` refuses. `coop init` explicitly targets that local
Git top. Bare repositories require a worktree or an explicit `--root`.

**Session pitfall**: Selector-free `coop exec` uses the declared `default_session` from `.amq/launch.json`, or `collab` (i.e., `.agent-mail/collab`). Outside `coop exec`, the base root is `.agent-mail` (no session suffix). These are different mailbox trees — don't mix them up.

### Root Resolution Truth-Table

| Context | Command | AM_ROOT resolves to |
|---------|---------|---------------------|
| Outside `coop exec` | `amq env --me claude` | resolved base root from project `.amqrc`, `AMQ_GLOBAL_ROOT`, or an eligible implicit fallback |
| Git worktree or bare repository, no project `.amqrc` | `amq env --me claude` | `AMQ_GLOBAL_ROOT` when set, otherwise repo-local detected `.agent-mail` |
| Git worktree or bare repository, no eligible root | `amq env --session auth --me claude` | refuses implicit `~/.amqrc`; requires a local or explicit root |
| Git worktree, no eligible root | `amq coop exec claude` | bootstraps `<git-top>/.agent-mail/collab`; never consults `~/.amqrc` |
| Git worktree, no eligible root | `amq coop exec --session auth claude` | bootstraps `<git-top>/.agent-mail/auth` |
| Git worktree, no eligible root | `amq coop exec --no-init claude` | refuses and names `amq coop init` as the remedy |
| Bare repository, no eligible root | `amq coop exec claude` | refuses; use a worktree or explicit `--root` |
| Outside `coop exec`, isolated session | `amq env --session auth --me claude` | `<resolved-base-root>/auth` |
| Inside `coop exec` (no flags) | automatic | `.agent-mail/collab` (default session) |
| Inside `coop exec --session X` | automatic | `.agent-mail/X` |

Canonical root precedence is:

```text
explicit --root > AM_ROOT > project-local .amqrc > AMQ_GLOBAL_ROOT > implicit fallbacks
```

Inside a Git worktree or bare repository, the remaining eligible fallback is repo-local detected
`.agent-mail`; outside Git, `~/.amqrc` precedes detected `.agent-mail`.

An initialized cwd-local queue is also a routing safety signal. If an active
pin points to another root, implicit participating commands refuse instead of
silently following that pin. Repin to the cwd-local queue, route deliberately
with `--session`/`--project`, or pass an explicit `--root` to confirm the
active queue; ordinary pin checks still apply.

### Git worktrees

A relative project root such as `{"root":".agent-mail"}` and auto-detected
roots are intentionally per-worktree. Two terminals in different git
worktrees can therefore use the same session name while reading different
mailboxes. If a delivery receipt times out, run `amq doctor --ops`; it can warn
when a peer has fresher presence in the same session under another worktree.

To share one mailbox across worktrees, use the same absolute root in each
worktree's machine-local `.amqrc`, or remove the project-relative `.amqrc` and
set `AMQ_GLOBAL_ROOT` to one absolute base. Keep the relative default when
per-worktree isolation is intended. A Git worktree with neither local
configuration nor a local queue fails closed instead of inheriting
`~/.amqrc`; this prevents accidental cross-project delivery. A nested or
linked worktree under a parent that already has `.amqrc` is the same
fail-closed ceiling: it uses its own config or refuses, and does not adopt
the parent live queue.

## Task Routing

Before diving in, match the task to the right workflow — this avoids wasted effort:

| Your task | What to do |
|-----------|-----------|
| **"spec", "design with", "collaborative spec"** | Use `/amq-spec` instead — it has structured phase-by-phase guidance for parallel-research workflows. |
| **Send a message, review request, question** | Use `amq send` (see Messaging below) |
| **Buzz / ACP / `amq-acp`** | Companion `amq-acp` queues to `AMQ_ACP_TO`; pool workers must not drain. Chat must not pass `--root`, recipients, or argv. `[Context]` is not routing. See [`cmd/amq-acp/README.md`](../../../cmd/amq-acp/README.md). |
| **Grok Bot runs commands on a registered Mac** | Ordinary local AMQ on that Mac. See [registered-machine execution](registered-machine.md); select the machine before resolving the project/session. |
| **Two separate host queues / Grok cloud computer / `amq-bridge`** | Companion `amq-bridge`, never a foreign `--root`. See Two-host fleets below. |
| **Swarm / agent teams** | Read [swarm-mode.md](swarm-mode.md), then use `amq swarm` |
| **Received message with labels `workflow:spec`** | Follow the spec skill protocol: do independent research first, then engage on the `spec/<topic>` thread — don't skip straight to implementation. |

## Quick Start

The repository [README Getting started](https://github.com/avivsinai/agent-message-queue#getting-started)
is the canonical human onboarding path. The commands below keep the agent
workflow self-contained.

```bash
# Interactive one-time project setup
amq setup

# Non-interactive setup: re-pass the same explicit inputs on preview and apply
setup_args=(--agents claude,codex --default-session collab --launcher-preference commands)
setup_preview="$(amq setup --preview --json "${setup_args[@]}")"
setup_digest="$(printf '%s\n' "$setup_preview" | jq -r '.preview.digest')"
amq setup --apply "$setup_digest" "${setup_args[@]}"

# Daily entry: reconcile the declared session (never creates an unknown name)
amq launch
amq session create feature-x   # once, before the first named-session launch
amq launch --session feature-x
amq session resume feature-x
```

`setup --preview` performs zero writes. On a fresh non-interactive setup,
`--agents`, `--default-session`, and `--launcher-preference` are required.
`--apply` recomputes the preview and exits `6` without writes unless the
approved `sha256:<hex>` digest matches. It is mutually exclusive with `-y`;
`--preview` is also mutually exclusive with `-y`.

For Cursor, setup uses the current `agent` command when it is on `PATH`; if it
is absent, the preview explains that setup is falling back to legacy
`cursor-agent`.

Grok Build is supported by the managed launch adapter. It mints an exact
`--session-id` from the AMQ launch nonce and resumes only with the stored
`--resume <UUID>`; `--continue`, `--always-approve`, and `--yolo` are rejected
from committed launch arguments. Grok tool policy uses its canonical
`--tools` and `--disallowed-tools` flags; do not translate those values through
Claude's `--allowedTools` grammar.

Put provider flags in the committed `.amq/launch.json` `command` arrays. The
launcher validates them and includes them in the semantic trust digest. The
first semantic plan, and each plan change, needs an interactive trust
confirmation stored outside the worktree. Non-interactive or `--json` calls
exit `6` until that digest is trusted. An unknown `session resume` name exits
`3` and writes nothing. Registered launchers are `commands`, `tmux`, `cmux`,
and `ghostty`. `--launcher auto` walks the local preference; an explicit
`--launcher <name>` wins. Inside cmux (`CMUX_SURFACE_ID`) is preferred over
inside Ghostty (`TERM_PROGRAM=ghostty`). Setup lists cmux and Ghostty as
available only when Detect ping succeeds, not from LookPath alone. The
`commands` backend prints complete `coop exec` commands and exits `6` because
running them is the remaining operator action. Paste the emitted lines exactly,
one per terminal; do not reconstruct them from generic `coop exec` examples.
Managed `tmux`, `cmux`, and `ghostty` backends run the plan in-app instead.

Without `--session` or `--root`, `coop exec` uses the declared `default_session` from `.amq/launch.json`, or `collab` when none is declared. Creating a missing session or root from `coop exec` is deprecated and prints `warning: creating a missing session or root from coop exec is deprecated; use 'amq session create <name>' or 'amq init --root'. The next major release makes this exit 3.`

Direct `coop exec` names the provider session by default as
`<session>/<handle>`, or as `<handle>` for a sessionless root. Claude and Pi
get `--name`; Codex uses its native naming API after process-bound thread
discovery, with a manual `/rename` fallback that does not affect queue delivery.
Cursor `agent` gets a best-effort TUI rename after the
new session store is verified. Codex resumes by name, for example `codex resume
session1/codex`. Cursor `agent` resumes through its picker only; resume-by-name
is unproven. Codex naming checks for an existing name immediately before setting
one; preservation is best effort because the native API has no atomic
set-if-unnamed operation. `--resume`, `-r`, `--continue`, or `-c` flags are
preserved, including `codex resume` and `agent --resume`. Disable naming
with `--named=false`, `AMQ_COOP_NAMED=0`, or
`"named": false` in `.amq/launch.json`. Managed launches keep naming disabled
until their provider-name contract is available; explicit `--named` remains
refused there.

Add `--no-gitignore` when `coop exec` should auto-initialize the project without changing `.gitignore`.

Direct `coop exec` is legacy low-level plumbing. When an operator deliberately
uses it, provider flags follow `--`; dangerous bypass flags belong only on this
operator-controlled path and are rejected from committed launch arguments:

```bash
amq coop exec claude -- --dangerously-skip-permissions
amq coop exec codex -- --dangerously-bypass-approvals-and-sandbox
amq coop exec grok
```

### Standalone wake interrupt safety

Standalone wake keeps urgent interrupt notices and the bell without injecting
Ctrl+C by default:
```bash
amq wake --me claude --interrupt-cmd none &
```

Swarm bridge events are hardcoded `priority=normal` plus label `swarm`, so do
not bind that combination to Ctrl+C. Use ordinary non-destructive wake:
```bash
amq wake --me codex --interrupt-cmd none &
```

`--interrupt-cmd ctrl-c` sends a real SIGINT to the foreground process group
and can interrupt or crash the agent. Use it only with a separate,
operator-controlled label/priority when process-level interruption is
intentional; the `interrupt` label alone never enables Ctrl+C.

## Statusline (Claude Code)

To show the current AMQ session in your Claude Code status bar, add this snippet to your statusline script (e.g., `~/.claude/statusline.sh`):

```bash
# AMQ session segment — try CLI first, fall back to env vars for older amq versions
amq_session=""
if _amq_out=$(amq env --session-name 2>/dev/null) && [ -n "$_amq_out" ]; then
    amq_session="$_amq_out"
elif [ -n "$AM_ROOT" ] && [ -n "$AM_BASE_ROOT" ] && [ "$AM_ROOT" != "$AM_BASE_ROOT" ]; then
    amq_session=$(basename "$AM_ROOT")
fi
if [ -n "$amq_session" ]; then
    output+=$(printf " | \033[33mamq:%s\033[0m" "$amq_session")
fi
```

`amq env --session-name` (v0.27+) prints the session name and exits 0 (empty when not in a session). The env-var fallback covers older versions. `amq env --json` also includes `session_name`.

To also set the terminal tab title (works in Ghostty, iTerm2, Terminal.app):

```bash
# Set tab title to "repo | amq:session" — re-asserts on each statusline refresh.
# Manual titles (e.g. Ghostty's prompt_tab_title) take priority and won't be overwritten.
tab_title="$repo_name"
[ -n "$amq_session" ] && tab_title+=" | amq:${amq_session}"
printf '\033]0;%s\007' "$tab_title" > /dev/tty 2>/dev/null
```

## Integration & Ops Quick Reference

```bash
# Global fallback for orchestrator-spawned agents
export AMQ_GLOBAL_ROOT="$HOME/.agent-mail"

# Symphony hooks
amq integration symphony init --me codex
amq integration symphony emit --event after_run --me codex

# Cline Kanban bridge
amq integration kanban bridge --me codex
amq integration kanban bridge --me codex --workspace-id my-workspace

# Runtime diagnostics
amq doctor --ops
amq doctor --ops --json
amq doctor --root <exact-root> --ops
amq wake check --me <agent>
amq wake check --me <agent> --json

# Base-config-only session repair outside the current pin
amq doctor --root <session-root> --base-root <base-root> \
  --ignore-session-pin --fix-mailboxes
```

## Exit Codes

Treat AMQ's process exit code as the stable machine contract:

| Code | Meaning |
|------|---------|
| `0` | Success. The command completed normally. |
| `1` | General error. The failure has no more specific exit-code classification. |
| `2` | Usage error. Arguments, flags, or command input are invalid. |
| `3` | Not found. A requested resource such as a mailbox, message, session, agent, or configuration does not exist. |
| `4` | Timeout. A watch, monitor, receipt wait, or delivery wait reached its deadline. |
| `5` | Context mismatch. A syntactically valid route was refused, including a pin conflict or an ineligible implicit root inside Git. |
| `6` | Action required. The command cannot proceed without an operator action (untrusted launch plan, unknown backend inspect, stale conversation token, blocked rebind, or emitted `coop exec` commands still to run). |

Do not parse stderr prose as a stable discriminator. `--json` preserves the
same process exit codes. A read-only `list` on a mismatched session pin warns
and continues; commands that consume or mutate mailbox state fail with code
`5`.

When a command reports per-agent outcomes, whole-command failures that precede
any per-agent work keep codes `2`, `5`, and `3` and preempt mixed results. Once
per-agent work begins, the process exit code is the highest-precedence per-agent
outcome: `6` over `4` over `1` over `0`. Expected dispositions (`disabled`,
`unsupported`, and policy-consistent `fresh`) contribute `0`. Launch Apply and
lifecycle JSON also carry a typed mutation disposition (`not_applied`,
`committed`, or `uncertain`) for the backend binding; that field is not a
process exit code.

## Delivery Receipts

AMQ records delivery outcomes in consumer-local receipt files. The main stages are:

- `drained` — a consumer successfully ingested the message
- `dlq` — the message was moved to the dead letter queue during ingest

Use these when you need confirmation rather than just fire-and-forget messaging:

```bash
# Block on delivery for a single-recipient send
amq send --to codex --body "please review" --wait-for drained --wait-timeout 60s

# Query receipt history later
amq receipts list --me codex --msg-id <msg_id>
amq receipts wait --me codex --msg-id <msg_id> --stage drained --timeout 60s
```

`amq read`, `amq drain`, and `amq monitor` all apply the same strict header validation. Messages in `inbox/new` that are corrupt or have malformed headers are moved to DLQ and produce a `dlq` receipt.

DLQ retries use four durable states: `ready`, `pending`, `delivered`, and
`indeterminate`. A successful retry retains a terminal audit in `dlq/cur` until
purge. `delivered` is idempotent and reports `already_delivered` plus
`audit_finalized`; `--force` cannot redeliver it. A `pending` or legacy
`indeterminate` envelope without a visible inbox destination refuses retry,
including with `--force`; that flag bypasses only the maximum retry count.
Bulk JSON separates `retried`, `already_delivered`, and `skipped`, and its
`count` includes only newly retried messages.

`amq who` and `amq doctor --ops` report `notifier_live` only when the wake-lock
inspector verifies a live `amq wake` process identity. That proves prompt
notification, not message consumption. `recent_activity` means only that
`last_seen` is fresh. Use `drain` or `monitor` when consumption is required;
run long-lived wake/monitor commands under launchd, systemd, or another
supervisor rather than treating AMQ itself as a daemon.

Before replacing a wake, run `amq wake check --me <agent> --json`. It is
read-only and reports the running/current image path and version plus an exact
`next_action`. An automated agent may act only when
`restart_capability=agent_safe`. For `operator_only`, leave the live wake
running and hand off to its owning terminal or supervisor. For `unavailable`,
preserve the state and diagnose it. Never kill a live raw wake from a non-TTY
process, and never accept an attention-only fallback as a replacement for
full-strength input delivery. When the recorded image or restart stage lives
under a directory that no longer exists, the check reports
`reason_code=binary_dir_gone` and names `amq doctor --ops --fix-wake-locks`
instead of a raw ENOENT.

Current resume-eligible `coop exec` wakes automatically observe their stable
AMQ launch symlink and adopt a strictly newer semantic version at a fully
quiescent boundary, preserving PID, terminal ownership, and unread messages.
Use `wake check --json --json-schema=2` to inspect `self_upgrade`; a failed
upgrade candidate is attempted at most once per candidate within one wake
generation, bounded to the 8 most recent distinct candidates, and a new
generation resets that refusal memory. `--no-self-upgrade` and `AMQ_WAKE_NO_SELF_UPGRADE=1` disable
this only for the launched wake. Ownerless, keepalive, repair, destructive
interrupt, arbitrary-inject, and pinned-path wakes remain manual.

Those consuming commands, `watch`, and all DLQ commands refuse a raw
target that conflicts with a complete `AM_BASE_ROOT`/`AM_SESSION` pin before
touching mailbox state. `send` and `reply` apply the same check to their source
context. Use `--session <name>` for deliberate sibling access. The raw-root
escape hatch, `--ignore-session-pin`, requires a non-empty explicit `--root`;
it never blesses an inherited `AM_ROOT`. `list` warns and remains available for
non-destructive inspection. With no session/tree evidence, scripts and CI
remain fail-open. A missing mailbox is an error, not an empty inbox. Empty
`drain` and `list --new` results may print a stderr note when the same handle
has pending messages in a sibling session; follow the exact `amq list --session
<name> --me <handle> --new` command in that note.
This is an operational safety check, not an authorization boundary; a local
process can deliberately repin or override it.

For `doctor`, `--root` selects the exact target but does not waive the active
pin. Read-only inspection continues and reports a mismatch warning.
`--fix-mailboxes` and `--ops --fix-wake-locks` require a matching pin unless an explicit non-empty
`--root` is paired with `--ignore-session-pin`. `--base-root` requires
`--root`, supplies retained config authority for the target or one direct
child, and never waives the pin.

## Session Layout

By default, the root is `.agent-mail` (from `.amqrc` or auto-detect). Use `--session` to create isolated subdirectories:

```
.agent-mail/              ← default root (configurable in `.amqrc`)
.agent-mail/auth/         ← isolated session (via --session auth)
.agent-mail/api/          ← isolated session (via --session api)
```

- `amq coop exec claude` → `AM_ROOT=.agent-mail/collab` (default session)
- `amq coop exec --session auth claude` → `AM_ROOT=.agent-mail/auth`

The main env vars are `AM_ROOT` (where) + `AM_ME` (who). `coop exec` also sets
`AM_BASE_ROOT` for cross-session resolution and `AM_SESSION` as the independent
session identity used by consuming-command guards. The CLI enforces correct
routing — run bare commands for the current session or use `--session` for a
named sibling.
Default `.agent-mail/<session>` layouts are recognized even without `.amqrc`; custom root names still need config or explicit flags/env.

## Cross-Project Routing

Send messages to agents in other projects via `--project` or inline `@project:session` syntax. Requires peer configuration in `.amqrc`.

**When to use `--session` vs `--project`**: `--session` = same project, different session. `--project` = different project. Change one dimension at a time.

### Peer setup

Add `project` and `peers` to your `.amqrc`:
```json
{
  "root": ".agent-mail",
  "project": "my-project",
  "peers": {
    "infra-lib": "/Users/me/projects/infra-lib/.agent-mail"
  }
}
```

Both projects must register each other as peers for round-trip messaging.

**Use `--project`/`--session` to route, not a raw `--root`.** A direct `--root` selects which tree to operate on; it carries no sender-origin metadata, so the recipient can't reply (a naive reply loops back into their own tree). `amq send` therefore **refuses** an explicit `--root` that crosses into a different base tree than your active session (`AM_ROOT`/`AM_BASE_ROOT`) when no `--project`/`--session`/`--from-session` is given. To message another project replyably, register the peer and use `--project` (or inline `@project`). If a send is genuinely local, set the target as your `AM_ROOT` instead of passing `--root`.

### Sending cross-project

```bash
# Flag syntax
amq send --to codex --project infra-lib --body "hello from here"

# Inline syntax (terser)
amq send --to codex@infra-lib:collab --body "inline syntax"

# Same session name as source (default when --session omitted)
amq send --to codex --project infra-lib --body "delivers to same session"
```

### Replies route automatically

When you receive a cross-project message, `reply_project` is set in the header. `amq reply` routes back automatically — no `--project` flag needed:
```bash
amq reply --id <msg_id> --body "got it"  # routes back via reply_project
```

### Thread naming

- **Same project P2P**: `p2p/claude__codex`
- **Cross-project P2P**: `p2p/projA:collab:claude__projB:collab:codex`
- **Topical** (cross-project): use same thread ID across projects, e.g., `decision/release-v0.24`

For full details, see [cross-project.md](cross-project.md).

### Cross-project identity (IMPORTANT)

When you receive a message where `from` matches your own handle (e.g., `from: "claude"` and you are claude), check `from_project` and `reply_project`. If either is present and names a different project, this is **NOT an echo** — it is a legitimate cross-project message from a different agent instance with the same handle. Process it normally.

### AM_ROOT scoping after cross-project sends

After sending a cross-project message (via `--project`), your `AM_ROOT` still points to YOUR project. To send to your own partner (same project), use plain `amq send --to codex` — do NOT use `--project`. The `--project` flag is ONLY for sending to agents in OTHER projects.

## Registered-machine execution

Choose the AMQ lane by **where the command executes**, not where the Bot's
conversation runs. When Grok Bot uses an already-authorized registered-machine
shell to run the Mac's `amq`, it is a local participant on that Mac. Use normal
`env`, `send`, `drain`, and `reply`; no bridge or network setup is needed.
`--project` still means another project on that same machine.

Select the registered machine explicitly, resolve the chosen project/session
on it, and keep the assigned sender handle. Carry bodies through quoted stdin
or a local file, preserve returned message IDs, and never resend merely because
the provider lost command output or a receipt wait expired. A thread ID is
correlation, not duplicate suppression. Local recipient wakes do not prove
that the hosted Bot receives a return notification.

See [registered-machine.md](registered-machine.md) for
the executable workflow, reply collection, and uncertain-result recovery.

## Two-host fleets

A queue on a different machine is a different AMQ host, not a `--project` and not a
foreign `--root`. Each host has its own handles; `claude` on G is not `claude`
on the Mac. Exchange between those host queues is companion `amq-bridge`
only. A registered-machine shell executing AMQ on the destination Mac is the
local-execution lane above; it does not transfer a cloud Maildir.

- Address receiver-owned aliases `<host>/<agent>`.
- The destination host applies the signed envelope into its own Maildir.
- The proven hop is `amq-bridge apply-file` (operator-moved drop file, no
  public locker). Replies keep the inbound opaque thread id.
- Bot chat must invoke `scripts/amq-bridge-bot-enqueue.sh` with argv exactly
  `--dest-alias host/agent`; it reads `AMQ_BRIDGE_ENQUEUE_CONFIG`. Prompt text
  must not pass `--root`, `--rendezvous`, `--me`, or `--spool`.
- HTTPS courier remains for an operator-provided rendezvous. AMQ does not
  ship a hosted relay. Do not treat a missing rendezvous as a reason to
  remote-drain or copy Maildirs.

See [amq-bridge](https://github.com/avivsinai/agent-message-queue/blob/main/cmd/amq-bridge/README.md).

## Decision Threads

Decentralized decision protocol using existing AMQ primitives (no new CLI commands).

- **Thread**: `decision/<topic>`
- **Kind**: `decision` for all messages
- **Labels**: `decision:proposal`, `decision:objection`, `decision:support`, `decision:final`; plus `project:<name>` for cross-project decisions
- **Context** on proposals: `{"proposal_id": "...", "question": "...", "options": [...], "required_projects": [...], "deadline": "..."}`

**Process**: Propose → Review/Object → Resolve objections → Close when all required projects responded and no unresolved blocking objections.

```bash
amq send --to codex --project infra-lib --kind decision \
  --labels "decision:proposal,project:my-project,project:infra-lib" \
  --thread "decision/api-v2" \
  --context '{"proposal_id":"api-v2","question":"Adopt new API?","required_projects":["my-project","infra-lib"]}' \
  --body "Proposal: migrate to API v2. All tests green."
```

## Session-Aware Routing

Users refer to sessions using many words: "session", "stream", "squad", "team", "workspace", "channel", or just a bare name. When the user mentions sending to or talking to an agent in a named context (e.g., "ask codex on stream1", "send to the auth team", "talk to codex in squad-api"), you must discover sessions before routing.

**Important**: Do not confuse sessions with projects. "Project" in AMQ means a different repo/codebase (cross-project routing via `--project`). Sessions are isolated mailbox trees within the same project (via `--session`). If the user says "the infra project", that likely means `--project infra`, not `--session infra`.

```bash
# Step 1: Discover active sessions and agents
amq who --json
# Returns: [{"name":"collab","agents":[...]},{"name":"stream1","agents":[...]},{"name":"auth","agents":[...]}]

# Step 2: Match the user's name against session names in the output, then send
amq send --to codex --session stream1 --body "Message for stream1"
```

**Recognition patterns** — any of these mean "route to a specific session":
- Explicit: "on stream1", "via auth", "in the api session", "the infra squad"
- Bare name: user just says "stream1" or "auth" — could be a session or an agent handle
- Colloquial: "team", "squad", "stream", "workspace", "channel" followed by a name

Note: The `agent@name` inline syntax (e.g., `codex@infra`) is for cross-project routing, not cross-session. For same-project session routing, always use `--session <name>` explicitly.

**Rules**:
1. When the user names something that could be a session, **always run `amq who --json` first** to check if it matches a known session name
2. If the name matches a session, use `--session <name>` on the send command
3. If it matches both a session and an agent handle, prefer the session interpretation when the user's phrasing implies a group/context ("on X", "in X", "the X team"), and the agent interpretation when it implies a person ("ask X", "tell X")
4. If the target session differs from your current session (`$AM_ROOT` basename), use `--session <name>`
5. Never guess — if the name doesn't appear in `amq who --json` output, tell the user (it may need `amq session create <name>`)
6. For cross-project routing (different repo), use `--project` instead — see Cross-Project Routing section

## Messaging

```bash
amq send --to codex --body "Message"              # Send (uses AM_ROOT/AM_ME from env)
amq drain --include-body                          # Receive (one-shot, silent when empty)
amq drain --session auth --include-body           # Deliberate sibling-session receive
amq reply --id <msg_id> --body "Response"          # Reply in thread
amq watch --timeout 60s                           # Block until message arrives (only when no wake is live for you)
amq list --new                                    # Peek without side effects
amq send --to grok --body "hello"                 # Grok is a normal peer handle, like codex or claude
```

For the live-wake receive rule and notify-only supervisor exception, see
[Receive under a live wake](../SKILL.md#receive-under-a-live-wake).

### Send with metadata
```bash
amq send --to codex --subject "Review" --kind review_request --body @file.md
amq send --to codex --priority urgent --kind question --body "Blocked on API"
amq send --to codex --labels "bug,parser" --context '{"paths": ["src/"]}' --body "Found issue"
echo "evidence: tests green" | amq send --to codex --subject "done" --body -   # - reads stdin
```

**Body is fail-closed.** `--body -` (or `--body @-`, or omitting `--body`) reads stdin; a literal string or `@file` is used as-is. A send whose resolved body is empty/whitespace is **rejected** with a usage error instead of delivering a blank message — so `--body -` with nothing piped fails loudly rather than shipping an empty body. Pass `--allow-empty` only when you truly want a blank body (subject carries everything).

**Unrouted self-addressing is fail-closed.** When `--to` resolves to your own handle and no `--project`, `--session`, or `--from-session` routing dimension is present, `amq send` refuses the ambiguous same-root send. Use routing to reach another instance of the same handle. Pass `--allow-self` only to confirm an intentional same-root self-send; it does not bypass cross-tree or session-pin guards.

**Send file paths, not file contents.** When attaching source code, configs, or large text for review, send the file path in the message body, not the contents inline. The receiver can open the file with their local tools. If the receiver cannot access that worktree, send a short diff instead of the full source.

### Filter
```bash
amq list --new --priority urgent
amq list --new --from codex --kind review_request
amq list --new --label bug
```

## Operator Gates

Almost all coordination is agent-to-agent. Occasionally the **next required actor is a human**: an approval, a manual test, a deploy only a person can run, or sign-off that a goal is complete. AMQ has no separate "gate" feature. You represent this **structurally**: address a message to the human's mailbox instead of describing the wait in prose to another agent.

The single invariant AMQ relies on here is **recipient-as-next-actor**: a message addressed to the human handle means a human is who must act next. Everything else below (the `gate/<topic>` thread name and the `APPROVAL:` / `DONE:` subject prefixes) is a **naming convention** that downstream tools like amq-noc watch for. AMQ routing and message classification do **not** special-case thread names or subject text; those are plain strings, useful only because humans and tooling agree to read them. They are conventions, not core AMQ semantics.

### The human handle is `user`

By convention the human/operator mailbox is `user`. AMQ reserves this handle for validation in configured projects, so `--to user` is accepted wherever the project has a configured agent list. New co-op projects include `user` in the default agent set. For explicit `amq init --agents ...` projects or older roots, initialize the mailbox layout before relying on human drain/receipt/DLQ ergonomics:

```bash
# Seed the human mailbox alongside the agents (one-time, per project)
amq init --root .agent-mail --agents claude,codex,user
# or, for a coop project:
amq coop init --agents claude,codex,user
```

Throughout this section, `user` means "the conventional human handle." In configured projects it is warning-free for strict handle validation; in older or explicitly seeded roots, make sure the `agents/user/` mailbox exists before expecting a human to drain and reply from it.

### Raising a gate

Use a stable `gate/<topic>` thread so a gate and its resolution stay together:

```bash
# Approval / choice / manual test a human must perform
amq send --to user --thread gate/<topic> --kind question \
  --subject "APPROVAL: <decision>" \
  --body "<what you need a human to approve or run, and why>"

# Human closeout of a completed goal (sign-off that the goal is done)
amq send --to user --thread gate/<topic> --kind decision \
  --subject "DONE: <goal>" \
  --body "<what was completed; what the human should confirm or close>"
```

The human answers on the **same** thread from their own terminal or client, e.g. `amq send --me user --to <agent> --thread gate/<topic> --kind answer --subject "APPROVED: <decision>" --body "<approval / answer text>"` (use `DENIED:` or `ANSWER:` for a rejection or a plain answer). Reusing the `gate/<topic>` thread is what lets a watcher pair the answer with the open gate and clear it.

### When NOT to raise a gate

Keep ordinary coordination agent-to-agent. Do **not** send to `user` for:

- FYIs and status updates -> `status` on a normal thread
- Acknowledgements
- Routine code review between agents -> `review_request` / `review_response`
- Agent-owned blockers (waiting on another agent, a build, or a flaky test)

If the escalation owner is a lead/CTO agent, **they** decide whether to escalate, and that decision is agent-to-agent. But once a human action is actually required, it still becomes a `to:user` gate so tooling can observe it.

### Anti-pattern

Prose like `operator-held`, `pending operator`, or `manual approval` **inside an agent-to-agent message is not a gate**. It is body text a human or tool has to guess at. If a human must act, address the human.

### What a gate is, and is not

- **It is an observability / handoff signal, not authorization or security.** AMQ sender identity is local convention, not authenticated approval. A `to:user` gate records that a human is the next actor; it does **not** grant permission or prove a human approved anything. Do not treat it as an access-control boundary.
- **Cross-session / cross-project gates must be intentional.** Default examples target the human mailbox in the **current** session/project. Routing a gate to another session's or project's `user` is a deliberate act (`--session` / `--project`), never the default. Gate-clearing is a consumer/orchestrator convention unless AMQ later adds explicit gate state.

## Priority Handling

| Priority | Action |
|----------|--------|
| `urgent` | Interrupt current work, respond now |
| `normal` | Add to TODOs, respond after current task |
| `low` | Batch for session end |

## Message Kinds

| Kind | Reply Kind | Default Priority |
|------|------------|------------------|
| `review_request` | `review_response` | normal |
| `question` | `answer` | normal |
| `decision` | — | normal |
| `todo` | — | normal |
| `status` | — | low |
| `brainstorm` | — | normal |

## References

For detailed protocols, read the reference file FIRST, then follow its instructions:

- [coop-mode.md](coop-mode.md) — Co-op protocol: roles, phased flow, collaboration modes
- [swarm-mode.md](swarm-mode.md) — Swarm mode: agent teams, bridge, task workflow
- [integrations.md](integrations.md) — Symphony + Kanban integration commands, global root fallback, ops checks
- [message-format.md](message-format.md) — Message format: frontmatter schema, field reference
- [cross-project.md](cross-project.md) — Cross-project routing: peer config, addressing, decision threads
- [amq-bridge](https://github.com/avivsinai/agent-message-queue/blob/main/cmd/amq-bridge/README.md) — Two-host courier: apply-file, identity, HTTPS rendezvous
- [amq-acp](https://github.com/avivsinai/agent-message-queue/blob/main/cmd/amq-acp/README.md) — ACP v1 stdio companion and Buzz BYOH JSON
- [review-loop.md](review-loop.md) — Token-efficient review cycles: delegate multi-round reviews to background agents

# AMQ through a registered-machine shell

Use this workflow when Grok Bot already has permission to execute commands on
the user's Mac. The provider transports the command and its output. AMQ runs
on the Mac and delivers local files. No cloud-to-Mac bridge, shared filesystem,
VPN, or new service is required for this lane.

This uses the local access the user already granted. It does not restrict a
general shell to AMQ. Sender handles and `origin:grokbot` labels are attribution,
not authentication or additional authority. Preserve the provider's approval
controls and the user's existing action limits.

## Select the execution machine first

Inspect the provider's available machine/tool metadata and select the intended
registered Mac explicitly. Grok Bot's local tools use a machine selector (the
0.43 client names `Shell`, `Read`, and `AwaitShell` with `machineId`). Verify the
live schema rather than copying an opaque machine ID from another session.
An unqualified cloud shell and a registered Mac shell are different contexts.

On the selected machine, confirm the AMQ executable with `command -v amq` and
its version with `amq --version`. Record the absolute executable and project
directory. Use the sender handle assigned to this Bot; do not select `user`
or borrow another running agent's handle. An existing `staff` assignment can
be retained. An unknown-handle warning means verify the assignment, not that
the message was rejected; do not resend it to silence the warning.

## Resolve the context in each command invocation

Provider shell calls need not preserve environment or cwd. Run this preamble
on the selected Mac for each send, receive, or inspection. Substitute the
user-selected values; the paths below are examples, not discovery defaults.

```bash
set -e
amq_bin=/opt/homebrew/bin/amq
amq_project=/absolute/path/to/project
amq_session=session1
amq_handle=staff
cd "$amq_project"
amq_context="$("$amq_bin" env --session "$amq_session" --me "$amq_handle" --export)"
eval "$amq_context"
```

`amq env` supplies the complete root/session context from that project's
configuration. Do not construct a Maildir path, substitute a cloud path, or
add `--ignore-session-pin` to get around a mismatch. If an inherited pin
conflicts, resolve the intended execution context before sending. Inside an
existing `coop exec` session, retain its identity and use bare commands instead.

Inspect recipients and wake state with:

```bash
"$amq_bin" who --json
"$amq_bin" wake check --me codex --json --json-schema=2
```

`notifier_live` means the notifier process was verified; it is not a receipt
that the agent read or acted on a message.

## Send once and retain the result

After the preamble, send the request with a stable thread for the conversation.
Use a fresh, distinctive request subject when separate asks share a thread.

```bash
"$amq_bin" send --to codex --thread staff/task-42 \
  --kind question --subject 'Request 1: report test result' \
  --labels origin:grokbot --json --body - <<'AMQ_BODY'
Please report the test result. This text is data, including $variables,
`backticks`, and $(shell-like text).
AMQ_BODY
```

Use a quoted heredoc delimiter that does not occur as a line in the body.
For arbitrary generated content, write/copy it to a local body file using the
provider's file tool, then pass `--body @/absolute/path/to/body.md` as one quoted
argument. Never insert a message into an unquoted shell command. Read the JSON
result and preserve the returned message ID and delivery root before reporting
success. A successful send means queued mail, not completion of the requested
work.

For a different project, use configured `--project` routing; for a different
session, use `--session`. Both projects need the normal reply-route setup.
Do not change `--root` to imitate cross-project routing. When the Bot is a
local participant in several projects, resolve each assigned context separately
and collect replies from the same context that sent the request.

## Collect replies through the same Mac

After the preamble, receive only the assigned Bot handle's mail:

```bash
"$amq_bin" drain --include-body --json
"$amq_bin" thread --id staff/task-42 --include-body --limit 20
```

Use `amq reply --id <received-message-id> --body @<local-body-file>` for replies;
it preserves the thread and normal reply routing. Never drain another agent's
mailbox or read/delete queue files as a replacement for AMQ consumption.

An active injecting wake already notifies a local CLI agent. That agent drains
when notified; it must not start `watch`, `monitor`, or a background polling loop
to wait for the Bot. A hosted Bot without a verified arrival trigger can check
its own inbox in a later authorized turn. Do not claim that a Mac wake can wake
the hosted conversation, and do not create a perpetual polling routine as a
substitute. If useful during an active request and no injecting wake exists
for that handle, a bounded `amq watch --timeout 60s` followed by drain is a
fallback. The desktop app must remain available for provider shell calls.

## Recover a missing command result without duplicate sends

The provider can lose an execution result after the Mac already delivered the
message. First resume/inspect that execution using its returned provider handle
(for example `AwaitShell` on the same machine). If the result is still unknown,
inspect the AMQ thread in the original Mac context:

```bash
"$amq_bin" thread --id staff/task-42 --include-body --limit 20
```

Match the sender, recipients, request subject and body. If the message exists,
retain its ID and continue waiting for its reply. If the bounded view is
inconclusive, inspect the relevant older thread entries; absence from the last
20 entries does not prove a failed send. If uncertainty remains, report it
instead of automatically sending again. AMQ thread IDs do not deduplicate
multiple sends.

`send --wait-for drained --wait-timeout 60s` is an optional receipt wait for one
recipient, not an arrival monitor. Its timeout does not mean delivery failed
and must not trigger a resend. A drained receipt means consumption, not task
success. Report queued, drained, and answered as separate observed states.

# Token-Efficient Review Loops

When a `review_request` may take multiple rounds, do not keep the whole loop in the main conversation. Use your host's background worker or subagent primitive so the AMQ exchange runs in isolated context and only the final verdict returns.

## Host Mapping

- Claude Code: use a subagent or background agent.
- Codex-based agents: use a spawned/background Codex worker or task.
- Tool names vary by host. The invariant is the same: intermediate AMQ rounds stay off the main thread.

## Pattern

- The background agent sends the initial `review_request` via `amq send`.
- It waits for replies with `amq drain --include-body`.
- If the reviewer finds issues, it applies fixes and re-sends for review.
- It stops when the reviewer says the change is green or a max round count is hit.
- It returns one line to the main context, for example: `reviewer signed off after 3 rounds, 5 findings fixed`.

## Why

- Intermediate review rounds stay out of the main context.
- Repeated diffs, logs, and review notes do not accumulate as stale history.
- The main conversation keeps only the durable outcome.

## Examples

```text
Claude Code:
Agent({
  run_in_background: true,
  task: `
    Send: amq send --to codex --kind review_request --body "Please review: src/foo.go"
    Loop up to 3 rounds:
    - amq drain --include-body
    - if codex is green, stop
    - apply the requested fixes
    - amq send --to codex --kind review_request --body "Updated: src/foo.go"
    Return one line only:
    "reviewer signed off after 3 rounds, 5 findings fixed"
  `
})
```

```text
Codex-style host:
Start a background worker/subagent for the AMQ review loop
- amq send --to codex --kind review_request --body "Please review: src/foo.go"
- amq drain --include-body
- apply fixes and re-send until green or max rounds
Return one line only:
"reviewer signed off after 3 rounds, 5 findings fixed"
```

This is behavioral guidance for agents using AMQ, not a CLI feature or protocol change.

# Swarm Mode: Agent Teams

Enable external agents (Codex, etc.) to participate in Claude Code Agent Teams by reading/writing the shared task list.

## Commands

```bash
amq swarm list                                    # Discover teams
amq swarm join --team my-team --me codex          # Join team
amq swarm tasks --team my-team                    # View tasks
amq swarm claim --team my-team --task t1 --me codex  # Claim work
amq swarm complete --team my-team --task t1 --me codex [--evidence '{"tests_passed":true}']  # Mark done
amq swarm fail --team my-team --task t1 --me codex --reason "tests red"  # Mark failed
amq swarm block --team my-team --task t1 --me codex --reason "waiting on API"  # Mark blocked
amq swarm bridge --team my-team --me codex        # Run task notification bridge
```

## Communication

Communication is asymmetric — bridge delivers task lifecycle notifications only:

- **Claude Code teammate → external agent**: works directly via `amq send`
- **External agent → Claude Code teammate**: relay through the team leader's AMQ inbox

```bash
# External agent sends to leader, noting the intended teammate
amq send --to claude --thread swarm/my-team --labels swarm \
  --subject "To: builder - question about task t1" --body "..."
```

The leader drains and forwards via Claude Code internal messaging.

## Bridge

`amq swarm bridge` watches the shared task list and delivers AMQ messages labeled `swarm` into the agent's inbox. Standard `amq wake` detects these automatically.

```bash
amq swarm bridge --team my-team --me codex --poll --poll-interval 5s &
```

## Task Workflow

1. `amq swarm list` — discover available teams
2. `amq swarm join --team <name> --me <agent>` — join a team
3. `amq swarm tasks --team <name>` — view available tasks
4. `amq swarm claim --team <name> --task <id> --me <agent>` — claim a task
5. Do the work
6. `amq swarm complete --team <name> --task <id> --me <agent> [--evidence <json>]` — mark done
7. `amq swarm fail --team <name> --task <id> --me <agent> [--reason <str>]` — mark failed
8. `amq swarm block --team <name> --task <id> --me <agent> [--reason <str>]` — mark blocked