agentainer 0.1.7 → 2.0.1

package/llms.txt

@@ -1,431 +1,147 @@
-# Agentainer
-
-> Agentainer runs several coding-agent CLIs (Claude Code, Codex, Gemini, Hermes) at once.
-> Each agent gets its own directory and its own tmux session. A single YAML file defines
-> the agents, the command that launches each one, its first prompt, and — as a strict
-> whitelist — which other agents it is allowed to message.
->
-> This file is the reference for LLMs asked to write or repair an Agentainer config.
-> If you are configuring a swarm, everything you need is below. Verify your work with
-> `agentainer validate --show-prompts`, which parses the config and launches nothing.
-
-## Mental model
-
-- One YAML file describes the whole swarm. `agentainer up` reads it and, for each agent:
-  creates `<root>/<name>/`, installs a turn-completion hook in that folder, opens a tmux
-  session named `<session_prefix><name>`, runs the agent's `command` inside the folder,
-  waits for its input box to become responsive, then types the assembled first prompt in.
-- Agents message each other with `swarm send --to <agent> "text"`. The `swarm` command is
-  on their `PATH` and `SWARM_AGENT` identifies them, so no `--from` is needed. Delivery is
-  refused unless the recipient appears in the sender's `can_talk_to`.
-- A delivered message is pasted into the recipient's pane as
-  `[swarm] message from <sender>:\n<text>`, archived under `.swarm/inbox/<recipient>/`,
-  and written to `.swarm/logs/`.
-
-## Config file
-
-Top level keys: `swarm`, `defaults`, `agent_types`, `agents`, `templates`.
-Only `agents` is required. Relative paths resolve against the config file's directory.
-
-```yaml
-swarm:
-  name: dev-swarm          # label used in prompts/logs; default = config filename
-  root: ./workspace        # parent of the per-agent folders; default ./workspace
-  create_workdirs: true    # auto-create missing agent folders; default true
-  session_prefix: ""       # prepended to tmux session names; default ""
-  send_delay_ms: 150       # pause before pasting into a pane
-  enter_delay_ms: 250      # pause between pasting and pressing Enter
-  max_forward_hops: 3      # auto-forward loop guard
-  ready_timeout_ms: 60000  # how long to wait for an agent's input box to respond
-  busy_timeout_ms: 900000  # after this, an agent stuck "busy" is treated as idle
-  message_format: tagged   # tagged | plain; tagged is the default
-  max_reply_reminders: 1   # how often to nudge an agent whose reply reached nobody
-  resume: false            # make `up` reattach to recorded conversations by default
-  pane_idle_ms: 2500       # quiet time before a `pane` capture counts as a finished turn
-  pane_poll_ms: 700        # pane sampling interval
-  pane_scrollback: 400     # lines of scrollback the pane watcher diffs
-  tmux_history_limit: 50000 # scrollback per agent pane so you can scroll up when attached; 0 = tmux default
-  tmux_mouse: true         # enable mouse-wheel scrolling in the panes
-
-defaults:                  # any agent key; applied to agents that omit it
-  type: claude
-  append_agents_that_you_can_talk_to_prompt: true
-  workdir: "{root}/{name}" # optional; see "Working directories" below
-
-agent_types:               # override built-ins, or define new types
-  claude:
-    command: "claude --dangerously-skip-permissions"
-    capture: hook
-    boot_delay_ms: 3000
-
-agents:
-  - name: developer        # REQUIRED. Used as the folder name AND the tmux session name.
-                           # Must match ^[A-Za-z0-9_][A-Za-z0-9_-]*$
-    type: codex            # claude | codex | gemini | hermes | any key in agent_types
-    command: "codex --yolo"          # exact CLI invocation; defaults to the type's command
-    can_talk_to: [reviewer]          # whitelist. "*" means every other agent. Default: []
-    first_prompt: |                  # typed in after the CLI boots
-      You are the DEVELOPER...
-    first_prompt_file: ./p.md        # alternative to first_prompt (mutually exclusive)
-    forward_responses_to: [reviewer] # auto-relay finished turns; must ⊆ can_talk_to
-    capture: hook                    # hook | pane | none | auto (default: from type)
-    boot_delay_ms: 3000              # grace period before probing the input box
-    ready_probe: true                # wait for the input box to echo a token first
-    busy_check: true                 # refuse incoming mail while this agent is mid-turn
-    parse_outbound_tags: true        # route <swarm-send> blocks written in its replies
-    reply_reminder: true             # nudge it when it owes a reply but sent nothing
-    resume_args: "--resume {session_id}"          # appended to command by `up --resume`
-    resume_command: "bash -ic 'chy3 --resume {session_id}'"  # or replace it entirely
-    workdir: ./somewhere             # default <root>/<name>; see below
-    create_workdir: true             # false => a missing workdir is an error
-    env: {KEY: value}                # extra env vars for its tmux session
-    append_agents_that_you_can_talk_to_prompt: true
-    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: false
-
-templates:                 # override the text Agentainer generates
-  comms: |                 # placeholders: {agent} {swarm} {peers} {prefix} {inbox} {workdir}
-    You are {agent}. You may message: {peers}.
-  task_notice: |
-    Stand by. Your real task arrives in the next message.
-  reply_reminder: |        # placeholders: {agent} {sender} {id} {peers} {problems}
-    You owe {sender} an answer to {id}. Send it inside <swarm-send to="{sender}">.
-  send_failed: |           # placeholders: {agent} {peers} {problems}
-    Your message could not be delivered. {problems}
-```
-
-## Working directories
-
-- Default: each agent gets `<root>/<name>`, created on `up`.
-- `workdir` overrides it. Absolute, relative to the config file, or `~`-prefixed.
-  Placeholders: `{name}` `{root}` `{swarm}` `{type}`.
-- `defaults.workdir` applies to every agent that omits it. Include `{name}` to give
-  each agent its own folder; omit it to put the whole swarm in one directory.
-- `create_workdirs` (swarm-level) and `create_workdir` (per-agent) control creation.
-  Set them to `false` when pointing at real repositories, so a mistyped path is an
-  error rather than a new empty folder.
-- Several agents may share one workdir. That is legitimate (pair programming in one
-  checkout) but they will overwrite each other's files and interleave git commits,
-  so `validate` and `up` print a warning.
-- `root` always holds `.swarm/` (logs, inboxes, the `swarm` shim), even when every
-  agent works elsewhere.
-
-## Tagged messages (the default wire format)
-
-Inbound, an agent sees an envelope it can parse unambiguously:
-
-    <swarm-message from="lead" to="reviewer" id="m-eb4105" reply-to="m-3f9a1c">
-    any number of lines, code blocks, backslashes -- all verbatim
-    </swarm-message>
-
-Outbound, the agent writes a block **in its reply**; the capture hook routes it when
-the turn ends. There is no shell involved, hence no quoting or escaping to get wrong:
-
-    <swarm-send to="reviewer" reply-to="m-eb4105">
-    multi-line body
-    </swarm-send>
-
-    <swarm-broadcast>
-    goes to everyone in the sender's can_talk_to
-    </swarm-broadcast>
-
-- `id` is generated per message; `reply-to` is optional and used for threading.
-- Tagged sends are permission-checked exactly like `swarm send`, and are queued
-  automatically if the recipient is busy.
-- A `<swarm-send to="...">` naming something that is not an agent is discarded with a
-  warning (this catches an agent echoing the `AGENT_NAME` placeholder from its prompt).
-- Blocks are removed from the text before `forward_responses_to` runs, so a message
-  addressed to one peer is not also auto-forwarded to everybody.
-- `message_format: plain` restores the `[swarm] message from <sender>:` header.
-  `parse_outbound_tags: false` stops reading tags out of replies. Both are forced off
-  when `capture: none`, since there is nothing to read.
-- With `capture: pane` the tags are recovered from scraped terminal text, so they are
-  only as reliable as the scrape. Prefer hook-captured agents for tag routing.
-
-## Resuming after a restart
-
-- Every captured turn records the agent's conversation id in `<root>/.swarm/sessions.yaml`
-  (claude hands it to the Stop hook; codex's is read from the newest rollout file under
-  that agent's private `CODEX_HOME/sessions`).
-- `swarm up --resume` rebuilds each agent's command from that id, skips re-sending the
-  first prompt, and preserves the agent's queued mail and any reply it still owes.
-- Resume recipes: claude `--resume {session_id}`, codex `resume {session_id}`. Neither
-  gemini nor hermes exposes a session id, so they always start fresh (with a warning).
-- `resume_args` is appended to `command`. If the command invokes the CLI through an
-  alias or wrapper (`bash -ic chy3`), appending is wrong -- set `resume_command` to the
-  full replacement, using `{session_id}` (and optionally `{command}`).
-- Starting an agent fresh removes its stale entry, so a later `--resume` cannot reattach
-  to a conversation that agent never ran.
-- `swarm sessions` prints what is recorded and the exact command that would resume it.
-
-## Reply reminders
-
-A model asked a question will often write the answer as prose and end its turn. That
-prose reaches nobody -- only a `<swarm-send>` block is delivered. So:
-
-- When agent B receives a message from agent A (and B may message A back), B is
-  recorded as owing a reply.
-- If B's turn ends having sent nothing, it is messaged with the `reply_reminder`
-  template: who is waiting, the message id to quote as `reply-to`, and the exact block
-  to write.
-- If B *tried* to send but the block was malformed -- unclosed, missing `to`, unknown
-  recipient, permission denied -- it gets the `send_failed` template naming each fault.
-- At most `max_reply_reminders` nudges (default 1), then Agentainer gives up silently.
-- Anything B delivered counts, including an auto-forward via `forward_responses_to`.
-  Reminders are sent from `swarm`, so they never create a reply obligation themselves.
-- `reply_reminder: false` disables it per agent; it is forced off when the agent's
-  tags are not parsed (`capture: none` or `message_format: plain`).
-
-## The two prompt switches
-
-Both are per-agent booleans, both default as shown, and both append to `first_prompt`:
-
-- `append_agents_that_you_can_talk_to_prompt` (default `true`) — appends a block naming
-  the agents this one may message and showing the `swarm send` / `swarm broadcast` / raw
-  `tmux send-keys` syntax. Set it to `false` for an agent with no peers, or when you want
-  to write the communication instructions yourself.
-- `in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt` (default `false`) —
-  appends a "do not start yet, your task arrives in the next prompt" block. Use it for
-  the agent you will drive manually with `swarm send`, so it acknowledges and waits
-  instead of inventing work.
-
-Final prompt order: `first_prompt`, then the comms block, then the task notice.
-
-## capture: how a finished turn is detected
-
-| value | works with | how |
-|---|---|---|
-| `hook` | `claude`, `codex` **only** | the CLI runs a program on turn completion; exact |
-| `pane` | anything | poll the tmux pane and diff it after `pane_idle_ms`; heuristic |
-| `none` | anything | no capture |
-| `auto` | anything | use the agent type's default (this is the default) |
-
-- `claude` → a `Stop` hook in `<agent-dir>/.claude/settings.json`; reads the transcript.
-- `codex` → a private `CODEX_HOME` at `<agent-dir>/.codex/` with a `notify` program.
-- `gemini`, `hermes` → no such facility, so they fall back to `pane`. Setting
-  `capture: hook` on them (or on a custom type) prints a warning and uses `pane`.
-- `pane` capture is terminal scraping. It filters the echo of incoming messages, but
-  spinners and redraws can leak through. When output quality matters, prefer
-  `capture: none` and tell the agent in its prompt to call `swarm send` itself.
-
-`forward_responses_to` requires `capture` to be `hook` or `pane`; combining it with
-`capture: none` is a config error.
-
-## Rules the validator enforces
-
-- agent names are unique and match `^[A-Za-z0-9_][A-Za-z0-9_-]*$`
-- every name in `can_talk_to` and `forward_responses_to` refers to a real agent
-- an agent may not list itself in `can_talk_to`
-- `forward_responses_to` ⊆ `can_talk_to`
-- `forward_responses_to` is empty unless capture is enabled
-- `type` is a built-in or defined under `agent_types`
-- `first_prompt` and `first_prompt_file` are not both set
-
-## Commands
-
-```
-agentainer up [--only a,b] [--restart] [--no-prompt] [--attach]
-agentainer down [--only a,b]
-agentainer restart
-agentainer status
-agentainer attach <agent>
-agentainer send --to <agent> [--from <name>] [--file F] [--queue] [--wait]
-                             [--wait-timeout S] [--ignore-busy] [--force] "message"
-agentainer broadcast "message"
-agentainer queue <agent> [--clear]
-agentainer idle <agent> [--no-drain]
-agentainer inbox <agent> [-n N]
-agentainer logs [agent] [-n N] [-f]
-agentainer validate [--show-prompts]
-```
-
-Config resolution: `-c PATH`, else `$SWARM_CONFIG`, else `./agents.yaml`, else the
-`agents.yaml` beside `agentainer`. `agentainer x.yaml` is shorthand for `up -c x.yaml`.
-
-## What an agent sees at runtime
-
-Environment inside every agent's tmux session:
-
-```
-SWARM_AGENT    this agent's name          SWARM_CONFIG   absolute path to the YAML
-SWARM_PEERS    comma-separated can_talk_to SWARM_ROOT    the swarm root directory
-SWARM_SESSION  its tmux session name       SWARM_NAME     the swarm's name
-PATH           has <root>/.swarm/bin first, providing `swarm`
+# 🐝 Agentainer
+
+> Zero-dependency multi-agent orchestrator with a file-based mail model. Launch
+> Claude Code, Codex, Gemini, or Hermes each in its own tmux session; let them
+> message each other only where `can_talk_to` allows. No runtime dependencies,
+> no API keys required to exercise the mechanics.
+
+## 🧭 What it is
+Agentainer v2 replaces v1's fragile "tagged XML envelope inside prose" messaging
+with a **file-based mail model**: agents *read a file* to receive and *write a
+file* to send. The orchestrator owns all hard logic — routing, ACL, message IDs,
+threading, read-state, queueing, retries, availability, the durable log. The
+model only reads and writes natural-language files.
+
+## 📬 Core model (two verbs, four folders)
+- Agents communicate by reading/writing files under their mail dir.
+- `inbox/` — the **one** current unread message (orchestrator releases one at a time).
+- `outbox/<name>/` — write here to send to `<name>`; read `<name>/about.md` for a contact card.
+- `read/` — move a handled message here (best-effort read receipt).
+- `sent/` — the agent's own record of delivered mail (orchestrator moves it here).
+- `failed/` — mail bounced by the orchestrator (ACL violation, etc.), with a `system` explanation.
+
+## 🔁 Why a rewrite
+v1 scraped messages out of a fullscreen-TUI pane. That was unreliable across LLMs.
+The v2 mail model works on nearly every tool-calling model, including weak ones.
+
+## 🚀 Quick start
 ```
-
-Sending, from inside an agent:
-
-```bash
-swarm send --to reviewer "src/parse.py is ready for review"
-swarm broadcast "I renamed the config module"
-tmux send-keys -t reviewer -l "raw fallback, skips permissions and logging" \
-  && tmux send-keys -t reviewer Enter
-```
-
-Loop guard: a forwarded message carries a hop count that increments on each relay and
-stops at `max_forward_hops`. A message you send with `swarm send` resets it to zero.
-
-## Worked examples in this repo
-
-- `examples/research-swarm.yaml` — hub and spoke: a lead delegates to a scout
-  (gemini), an analyst (codex) and a writer; the writer uses a custom `workdir`.
-- `examples/software-company.yaml` — six agents across all four CLIs with a
-  restricted comms graph (developers talk to the architect and QA, never to
-  each other).
-- `examples/bug-hunt.yaml` — a hands-free pipeline built on `forward_responses_to`:
-  reproduce → diagnose → fix → verify.
-- `examples/existing-repo.yaml` — two agents pairing inside one existing checkout,
-  using `create_workdirs: false` so a wrong path fails instead of being created.
-- `examples/red-team.yaml` — adversarial triad: an attacker and defender argue
-  through a referee over one existing checkout.
-- `examples/debate.yaml` — two advocates argue opposite sides; a judge
-  cross-examines and rules.
-- `examples/writers-room.yaml` — an editor drives a writer, fact-checker and
-  critic to a finished article.
-- `examples/incident-response.yaml` — a commander coordinates an investigator,
-  responder and scribe under time pressure (hub and spoke).
-- `examples/tdd-pingpong.yaml` — a tester and coder grow a feature test-first,
-  one test at a time, via `forward_responses_to`.
-- `examples/brainstorm.yaml` — three idea-generators fan out from a facilitator,
-  then a synthesiser ranks them.
-- `examples/localization.yaml` — translate → review → back-check, auto-forwarded
-  via `forward_responses_to`; a `NEEDS ANOTHER PASS` verdict loops back to
-  the translator with a `<swarm-send>` block.
-- `examples/multi-language-broadcast.yaml` — one translator broadcasts a source to
-  N language reviewers; a consolidator compiles and broadcasts back. Built on
-  `broadcast`.
-- `examples/code-review-broadcast.yaml` — a coordinator broadcasts a PR to
-  specialist reviewers (correctness/security/perf); each replies to the
-  coordinator, who synthesizes. Built on `broadcast`.
-- `examples/ping-pong.yaml` — two agents trade a unit of work, each broadcast
-  naming who is up next (round-robin via `broadcast`, distinct from
-  tdd-pingpong's fixed `forward_responses_to`).
-- `agents.example.yaml` — the fully annotated reference config; every key is
-  documented inline.
-
-## Recipes
-
-**Hub and spoke** — one orchestrator drives specialists, which reply only to it:
-
-```yaml
-agents:
-  - {name: orchestrator, type: claude, can_talk_to: "*",
-     in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true}
-  - {name: researcher, type: gemini, can_talk_to: [orchestrator]}
-  - {name: developer,  type: codex,  can_talk_to: [orchestrator]}
+cp examples/quickstart.yaml my-swarm.yaml
+agentainer up       -c my-swarm.yaml
+agentainer status   -c my-swarm.yaml
+agentainer send     -c my-swarm.yaml --to orchestrator "Build a CSV->Parquet CLI."
+agentainer logs     -c my-swarm.yaml -f
+agentainer down     -c my-swarm.yaml
 ```
-
-**Pipeline** — each stage hands off to the next, automatically:
-
-```yaml
-agents:
-  - {name: spec,   type: claude, can_talk_to: [build], forward_responses_to: [build]}
-  - {name: build,  type: codex,  can_talk_to: [review], forward_responses_to: [review]}
-  - {name: review, type: claude, can_talk_to: []}
-```
-
-**Isolated worker** — runs alone, talks to nobody:
-
-```yaml
-agents:
-  - {name: scribe, type: hermes, can_talk_to: [], capture: none,
-     append_agents_that_you_can_talk_to_prompt: false}
-```
-
-## Busy agents (backpressure)
-
-- An agent is "busy" from the moment a message is submitted to it until its next
-  captured turn end. Sending to a busy agent is refused with a message telling the
-  sender to retry later, `--queue`, or `--wait`.
-- `--queue` appends to `<root>/.swarm/run/<agent>.queue.jsonl`; the capture hook that
-  ends the agent's turn drains one message from it. `--wait` blocks until deliverable.
-  `--queue --wait` queues, then blocks until the agent picks the message up.
-- The busy check and the "now busy" write happen inside the recipient's pane lock, so
-  two parallel senders can never both see an idle agent and both deliver.
-- Turn state is two counters (`delivered`, `completed`), not a boolean: a hook that
-  ends turn N may land after a message delivered during turn N. `completed` is clamped
-  to `delivered` on each turn end, because codex folds a queued message into the turn
-  already running, and an incrementing counter would drift and wedge the agent "busy".
-- Only works when the agent is captured. `capture: none` => `busy_check` is forced off
-  and the agent always accepts mail.
-- `busy_timeout_ms` fails open if a capture never fires; `swarm idle <agent>` clears it.
-- Auto-forwarded responses to a busy peer are queued rather than dropped.
-- Queues self-heal: every turn end sweeps other agents and drains any that have gone
-  idle (or gone stale-busy past `busy_timeout_ms`), so a single missed turn-completion
-  cannot strand queued mail forever. A capture only fires when `type` matches the CLI
-  the `command` actually launches — a `type: codex` agent running `claude` never reports
-  turn ends and looks busy forever.
-
-## Subagents and concurrency
-
-- A subagent inherits `SWARM_AGENT`, so `swarm send` from inside one is attributed to
-  the parent agent and checked against the parent's `can_talk_to`.
-- Every write into a pane takes a per-recipient lock (`<root>/.swarm/run/<session>.lock`).
-  Without it, parallel senders interleave: a paste and its Enter are two tmux calls, so
-  one Enter can submit two concatenated messages and another submit nothing.
-- A message delivered to a busy agent is queued by the CLI and processed after the
-  current tool call. It is not lost.
-- `capture: hook` fires when the *agent's* turn ends. Claude `Task` subagents run inside
-  the turn, so the hook waits for them. Backgrounded work ends the turn early: the
-  interim "I will respond when the subagent finishes" is captured (and forwarded), then
-  the real answer is captured when the agent finishes for real. The hop counter stores
-  the hop at which the agent last *received* a message, so a second response reuses the
-  same hop and the loop guard never suppresses the real answer.
-- Claude records subagent turns in the same transcript with `isSidechain: true`. The
-  Stop hook skips them, so subagent chatter is never relayed as the agent's answer.
-- `capture: pane` cannot tell "waiting on a subagent" from "finished": a quiet pane is
-  its only signal, so it forwards the interim message and then the real one. Raise
-  `pane_idle_ms`, or use `capture: none`.
-
-## Verified CLI behaviours (do not "simplify" these away)
-
-- The claude `Stop` hook entry must have **no `matcher` key**. With one, the interactive
-  TUI never runs the hook (headless `-p` still does, which makes this easy to miss).
-- Claude fires `Stop` *before* flushing the assistant message to the transcript. Read it
-  with a short poll, and only consider text after the last user record -- otherwise the
-  hook captures nothing, or re-relays the previous turn's reply.
-- Claude asks "do you trust this folder?" in any new directory, even under
-  `--dangerously-skip-permissions`. Pre-trust it by setting `hasTrustDialogAccepted`
-  for that path in `~/.claude.json` before launching.
-- Long pastes are collapsed into a chip: `[Pasted text #1 +N lines]` (claude),
-  `[Pasted Content N chars]` (codex). Delivery checks must recognise both.
-
-- Claude Code discards keystrokes for several seconds partway through startup
-  (measured on v2.1.205: t=2s landed, t=6s and t=12s were dropped, t=20s landed).
-  A fixed `boot_delay_ms` cannot fix this, which is why `ready_probe` types a
-  throwaway token until the input box echoes it, and why a paste is verified on
-  screen before Enter is pressed.
-- Codex shows a "do you trust this directory?" modal on first run in a new folder;
-  Enter answers the modal instead of submitting the prompt. The generated
-  `<agent>/.codex/config.toml` pre-trusts the agent's workdir to avoid it.
-- TOML is order-sensitive. In that generated config, `notify` must appear above
-  every `[table]` header, or it becomes `projects.<dir>.notify` and codex never
-  calls it.
-- Claude collapses a long paste into a `[Pasted text #1 +N lines]` chip, so the
-  pasted text never appears verbatim on screen. Delivery checks look for the chip
-  as well as for the tail of the pasted text (the head scrolls out of view).
-
-## Gotchas
-
-- A folder and a tmux session are named after each agent; renaming an agent orphans both.
-- Pointing several agents at one `workdir` is allowed and warned about; they share a
-  filesystem and a git index, so they can clobber each other.
-- Two agents with `forward_responses_to` pointing at each other will relay until the hop
-  limit stops them. Prefer one-directional forwarding, or none.
-- `--dangerously-skip-permissions` / `--yolo` let agents run tools unsupervised. Point
-  `root` at a disposable directory.
-- The first prompt is typed into a live TUI. If Agentainer reports "could not confirm
-  the text arrived", the CLI is usually stuck behind a modal (login, trust, onboarding);
-  attach to the session and look. Raise `ready_timeout_ms` if it is merely slow.
-- PyYAML is used when installed; otherwise a bundled subset parser handles the config.
-  It supports block maps/sequences, `|` and `>` scalars, flow `[a, b]` / `{a: 1}`,
-  comments and quoting — but not anchors, aliases, tags or multi-document files.
-
-## Files
-
-- [tests/validate.sh](tests/validate.sh): the full suite. Run it after any change; it
-  uses mock agents, so it needs no API key. 48 checks, all must pass.
-- [agents.example.yaml](agents.example.yaml): every option, documented inline.
-- [README.md](README.md): human-facing guide, architecture and troubleshooting.
-- [lib/config.py](lib/config.py): schema, defaults and validation — the source of truth.
-- [lib/swarm.py](lib/swarm.py): tmux orchestration, message routing, capture.
-- [hooks/](hooks/): the Claude `Stop` hook and the Codex `notify` program.
+(Install via `npm install` + `npm link` so the `agentainer` bin is on PATH.)
+The quickstart uses `bash` loop "mock agents" (no API keys) so you can watch the
+mailroom route mail safely. Swap each `command` for a real agent CLI to run for real.
+
+## 🔒 Key invariants
+- Zero runtime dependencies (Python 3 + bash + tmux; PyYAML optional, bundled `minyaml` fallback).
+- `can_talk_to` ACL is cooperative, documented honestly, not an OS boundary.
+- `user`/`system` are reserved virtual mailboxes.
+- Liveness supervisor heartbeat retained (no event-only redesign).
+- Durable JSONL event log is the source of truth for history.
+
+## 🛠️ Commands
+- `validate` — resolve and print the config; launch nothing.
+- `up` — create dirs + mailbox folders, install per-type turn-detection, open one tmux session per agent, send the role.
+- `down` / `restart` — tear down / down+up.
+- `status` / `attach` / `logs` — health, attach, durable JSONL log (`-f` follows).
+- `send` — send a `user` message into the swarm (`--to <agent>`).
+- `user` — toggle `user` availability (`available`/`away`/`inbox`/`send`).
+- `queue` / `inbox` / `idle` — inspect pending mail, current inbox, idle agents.
+- `hook` / `watch` / `supervise` — turn-completion hook, live pane watch, liveness supervisor.
+- `serve` — mail-app control-plane UI on `127.0.0.1` (per-agent threaded mail rendered as markdown with delivery status, reply as `user`, activity timeline + topology graph, live tmux pane + direct type-in, availability toggle, swarm-settings & agent add/edit/delete written back to YAML, and an optional stdlib Telegram bridge that mirrors mail out and routes phone replies back as `user` mail); token required for non-loopback.
+- `add <name> --type T --command C --can-talk-to X` — add an agent to the config and bring it up.
+- `edit <name> -s key=value` — edit an agent's fields and reconcile.
+- `remove <name>` — remove an agent and stop its session.
+- `reconcile` — start agents missing from the running set / stop orphaned sessions.
+
+## 🖥️ Control-plane UI (P2–P3)
+`agentainer serve -c swarm.yaml --port 8080 --token <secret>` serves a zero-dependency
+UI (stdlib `http.server` + one vanilla-JS page; no framework, no build). It shows
+swarm/agent status, logs, inbox, queue, a live terminal snapshot of each agent's tmux
+pane, and lets you inject mail as the `user` mailbox. Binds `127.0.0.1` by default;
+a token is required for any non-loopback bind (the UI is a control plane).
+
+## 🔄 Dynamic reconcile (P4)
+Change the swarm without a full teardown: `add`/`remove`/`edit` rewrite `agentainer.yaml`
+with a stdlib-only YAML emitter (works with or without PyYAML) and then `reconcile` the
+change into effect.
+
+## ✅ Verified CLI behaviours (do not "simplify" these away)
+These are observed, load-bearing behaviours of the shipping CLI. An LLM patching or
+"tidying" a config/command around them will produce a subtly broken swarm — keep them.
+
+- **`validate` launches nothing.** It resolves and prints the config only. Safe to run
+  in any environment.
+- **`up` installs per-`type` turn detection.** `claude` → Stop hook; `codex` → `notify`
+  program; `gemini`/`hermes` → pane polling. This wiring is what makes completion
+  detectable; do not assume a bare tmux session is enough.
+- **One message in `inbox/` at a time.** The orchestrator releases the next message
+  only after the current one is handled (moved to `read/`, or auto-archived after N
+  presentations). An agent never sees a queue of inbox files.
+- **Outgoing mail is swept on stop, not in real time.** Writes to `outbox/<name>/` are
+  routed when the agent's turn finishes (Stop hook / `notify` / supervisor tick), not
+  the instant the file appears. A long-running turn does not deliver mid-turn.
+- **Every delivered message is stamped** with `From:` / `To:` / `Id:` / `Time:` /
+  `Re:` headers by the orchestrator; the sender only wrote natural-language body text.
+- **ACL is enforced at routing.** A send to a name not in `can_talk_to` is bounced: a
+  `system` explanation is dropped in the sender's `inbox/` and the file moved to
+  `failed/`. `"*"` means everyone-else.
+- **`user` send is held, not bounced, when unavailable.** If `user` is in `can_talk_to`
+  but `user` availability is `away`, the mail is queued and a `system` ack is returned;
+  it is released when `user` becomes `available`.
+- **`read/` is a best-effort receipt.** Moving mail there marks the sender's `sent/`
+  copy read; if the model forgets, the orchestrator auto-archives after N presentations
+  so a forgetful agent can't wedge or loop the system.
+- **ACL membership = presence of `outbox/<name>/` + `about.md`.** The orchestrator
+  creates these when `can_talk_to` includes the name; the model reads `about.md` as a
+  contact card. Don't hand-create these folders expecting routing to follow.
+- **`type` ↔ `command` mismatch is a hard error at `up`.** If `command` launches a
+  different CLI than `type` implies, `up` fails with `ConfigError` instead of silently
+  pinning the agent `busy` forever.
+- **`capture: none` auto-upgrades to `hook` on hook-backed types** (`claude`/`codex`)
+  at config load, with a warning — a `none` capture on those types would blind turn
+  detection.
+- **`add`/`remove`/`edit` rewrite the YAML with the stdlib emitter** and then
+  `reconcile`; they work with *or without* PyYAML. Don't assume PyYAML is present.
+- **The liveness supervisor is always on at `up`.** It reconciles stale-busy, dead, and
+  silent-but-alive agents every tick; `status` reports `supervisor: alive|down`.
+
+## ⚠️ Gotchas (the quirks that look like bugs but aren't)
+- **Mail sits in `outbox/<name>/` until the turn ends.** If you `send` as an agent and
+  immediately check the recipient's `inbox/`, it may not be there yet — wait for the
+  sender's turn to finish (or the next supervisor tick).
+- **`inbox/` holds exactly one file.** Don't script around "the newest of many inbox
+  files"; there is never more than one.
+- **A `system` mail in `inbox/` is not spam** — it's the orchestrator talking back
+  (bounce explanation, nudge ack, ping). Treat it as first-class input.
+- **`failed/` means "the orchestrator refused this", not "a crash".** Almost always an
+  ACL violation. Read the `system` note inside the file.
+- **`user` is a virtual mailbox, not an agent.** `--to user` routes to the operator;
+  `user` availability gates delivery (hold-not-bounce). There is no `user` tmux session.
+- **Reserve the names `user` and `system`.** A real agent may not claim them; the
+  validator rejects it.
+- **Mismatched `type`/`command` deadlocks silently** if you bypass the validator (e.g.
+  hand-editing the YAML and skipping `validate`). Always `validate` before `up`.
+- **`capture: none` is only valid for pane-polling types** (`gemini`/`hermes`). On
+  `claude`/`codex` it is auto-corrected to `hook`; if you really need no detection,
+  expect that agent to never report completion.
+- **The no-PyYAML path is supported but stricter.** The bundled `minyaml` parser does
+  not support multi-document YAML, anchors, or tags. Keep real configs single-document
+  and you'll never notice.
+
+## 📊 Project status
+- **P1 — Mail runtime (CLI-driven)**: ✅ done.
+- **P2 — UI observability**: ✅ done.
+- **P3 — terminal snapshot + send-from-UI**: ✅ done.
+- **P4 — dynamic reconcile (`add`/`remove`/`edit`/`reconcile`)**: ✅ done.
+- 100% line coverage across all core + UI + reconcile modules, via mock agents (no API keys).
+
+## 📚 Docs
+- `ProjectPlan.md` — the design (source of truth).
+- `README.md` — user-facing overview, install, commands, FAQ.
+- v1 reference (read-only): `/root/AgentSwarm/docs/PROJECT-DOCUMENTATION.md`.