agentainer 0.1.7 → 2.0.0

package/README.md

@@ -1,727 +1,298 @@
-<!-- Banner -->
-<p align="center">
-  <img alt="Agentainer — multi-agent orchestrator for AI coding agents" src="https://raw.githubusercontent.com/mehmetcanfarsak/AgentSwarm/main/assets/banner.svg" width="820">
-</p>
+# 🐝 Agentainer
 
-<!-- Badges -->
-<p align="center">
-  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue.svg">
-  <img alt="zero deps" src="https://img.shields.io/badge/dependencies-zero-brightgreen.svg">
-  <img alt="platform" src="https://img.shields.io/badge/platform-linux%20%2F%20macOS-lightgrey.svg">
-  <img alt="tests" src="https://img.shields.io/badge/tests-48%20checks%20passing-success.svg">
-</p>
+**Zero-dependency multi-agent orchestrator with a file-based mail model.**
 
-<h1 align="center">Agentainer — Multi-Agent Orchestrator for AI Coding Agents</h1>
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![runtime deps: zero](https://img.shields.io/badge/deps-zero-blue.svg)](https://github.com/mehmetcanfarsak/Agentainer#readme)
+[![platform: linux | macOS](https://img.shields.io/badge/platform-linux%20%7C%20macOS-lightgrey.svg)](https://github.com/mehmetcanfarsak/Agentainer#readme)
+[![line coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/mehmetcanfarsak/Agentainer#readme)
 
-<p align="center">
-  <strong>A zero-dependency multi-agent orchestrator for AI coding agents.</strong><br>
-  Run a team of <b>Claude Code</b>, <b>OpenAI Codex</b>, <b>Gemini CLI</b>, and <b>Hermes</b> side by side in <b>tmux</b> — each in its own directory, each messaging the others only where your config allows.
-</p>
+> **Formerly AgentSwarm.** The v1 project was renamed and rewritten around a
+> file-based mail model — the old name still resolves to this repo.
 
-<p align="center">
-  <em>Formerly <strong>AgentSwarm</strong>. Installed globally the command is <code>agentainer</code>; from a clone, <code>./agentainer</code> in the repo root is identical.</em>
-</p>
+Agentainer launches AI coding agents (Claude Code, Codex, Gemini, Hermes) each in
+its own `tmux` session and working directory, defined by a single
+`agentainer.yaml`. They talk to each other only where the config's `can_talk_to`
+ACL allows — by **reading a file** to receive and **writing a file** to send.
 
-**Agentainer** is a lightweight, stdlib-only orchestrator (Python 3 + bash + tmux, no runtime dependencies) that launches multiple AI coding agents — Claude Code, OpenAI Codex, Google's Gemini CLI, and Hermes — in isolated tmux sessions, each with its own working directory, and routes messages between them under a configurable access-control list. Define your whole agent team in a single YAML file; one command brings it online.
+No runtime dependencies. No API keys required to exercise the mechanics. Agents
+only need to read and write natural-language files; the orchestrator owns all the
+hard logic (routing, ACL, message IDs, threading, read-state, queueing, retries,
+availability, the durable log).
 
-<!-- Demo -->
 <p align="center">
-  <img alt="Terminal demo: agentainer up starts four agents, status shows them running, send delivers a task, and logs stream the routed messages" src="https://raw.githubusercontent.com/mehmetcanfarsak/AgentSwarm/main/assets/demo.svg" width="760">
-  <br>
-  <em>Start a four-agent swarm, check status, hand it a task, and watch the messages route — in four commands.</em>
+  <img src="https://raw.githubusercontent.com/mehmetcanfarsak/Agentainer/main/assets/banner.svg" alt="Agentainer banner: zero-dependency multi-agent orchestrator with a file-based mail model" width="720"/>
 </p>
 
+> v2 replaces v1's "tagged XML envelope emitted inside prose and scraped out of a
+> TUI pane" — that was unreliable across LLMs. The file-based mail model works on
+> nearly every tool-calling model, including weak ones.
+
 ---
 
-## <span id="table-of-contents"></span>Table Of Contents
+## 📑 Contents
 
-- [Why Agentainer](#why-agentainer)
-- [How it fits together](#how-it-fits-together)
-- [Requirements](#requirements)
 - [Install](#install)
-- [Quickstart](#quickstart)
-- [FAQ](#faq)
-- [How it works](#how-it-works)
-- [Capturing what an agent says](#capturing-what-an-agent-says)
-- [Subagents, parallel work, and busy agents](#subagents-parallel-work-and-busy-agents)
-- [Configuration reference](#configuration-reference)
-- [Examples](#examples)
+- [Quick start (no API keys)](#quick-start-no-api-keys)
+- [The model in one screen](#the-model-in-one-screen)
+- [Architecture](#architecture)
 - [Commands](#commands)
-- [Project layout](#project-layout)
-- [Tests](#tests)
-- [Troubleshooting](#troubleshooting)
-- [A note on flags](#a-note-on-flags)
-
-
-## <span id="why-agentainer"></span>✨ Why Agentainer
-
-- **Multi-agent, one command.** Spin up a whole team with `agentainer up` — folders, hooks, tmux sessions, and first prompts, all wired automatically.
-- **Zero runtime dependencies.** Just Python 3 + bash + tmux. No pip installs, no bloated toolchain.
-- **Real ACLs, not vibes.** Agents only message who your YAML `can_talk_to` list permits. `"*"` for everyone, an explicit list for tight graphs.
-- **Survives restarts.** Each turn's conversation id is recorded; `up --resume` reattaches instead of starting cold.
-- **Self-healing routing.** Busy agents queue inbound work, stranded messages get swept, and agents are nudged when a reply reaches nobody.
-- **Any mix of CLIs.** Claude, Codex, Gemini, Hermes — or your own type — in the same swarm.
-
-## <span id="how-it-fits-together"></span>🏗️ How It Fits Together
-
-*Architecture at a glance: a single `agents.yaml` file maps each AI coding agent to its own tmux session and working directory, while Agentainer routes and logs every message between them under a `can_talk_to` access-control list.*
-
-<p align="center">
-  <img alt="Agentainer architecture: one YAML file maps each agent to its own tmux session and working directory; Agentainer routes and logs permission-checked messages between them" src="https://raw.githubusercontent.com/mehmetcanfarsak/AgentSwarm/main/assets/architecture.svg" width="900">
-</p>
-
-One command starts the swarm: it creates a folder per agent, installs a
-completion hook inside each folder, opens a tmux session per agent, launches
-the CLI, and types each agent's first prompt into it.
-
-<details>
-<summary>Plain-text diagram</summary>
-
-```
-   agents.yaml                 tmux
-  ┌────────────┐        ┌──────────────────┐
-  │ orchestr.  │───────▶│ session: orchestr│──┐
-  │ researcher │        │ session: research│  │  swarm send --to developer "..."
-  │ developer  │        │ session: develop │◀─┘
-  │ reviewer   │        │ session: reviewer│
-  └────────────┘        └──────────────────┘
-         │                       │
-         │  workspace/<agent>/   │  hooks capture each finished turn
-         ▼                       ▼
-   one folder per agent    messages routed + logged
-```
-
-</details>
+- [Key invariants](#key-invariants)
+- [The control-plane UI (P2–P3)](#the-control-plane-ui-p2p3)
+- [Dynamic reconcile (P4)](#dynamic-reconcile-p4)
+- [Project status](#project-status)
+- [FAQ](#faq)
+- [License](#license)
 
 ---
 
-## <span id="requirements"></span>📋 Requirements
-
-- **`tmux`** (3.0+)
-- **`python3`** — PyYAML is used if present, otherwise a bundled parser handles the config
-- **`node`** (16+) — only for the global `agentainer` command; not needed if you run `./agentainer` from a clone
-- whichever agent CLIs you reference: `claude`, `codex`, `gemini`, `hermes` — install only the one(s) you actually use
-
-## <span id="install"></span>🚀 Install
-
-**Global, via npm:**
+## 📦 Install
 
 ```bash
-npm install -g agentainer
-agentainer --version     # print the installed version (also: agentainer -v)
-agentainer doctor        # check tmux/python3 are present; report which agent CLIs it found
+git clone <repo> && cd Agentainer
+npm install            # runs the postinstall dep check; no build step
+npm link               # puts the `agentainer` bin on your PATH
+agentainer --version
 ```
 
-`agentainer doctor` verifies the required tools (`tmux`, `python3`) and reports
-which agent CLIs are available — it never fails on a missing *agent* CLI, since
-you may only use one of them.
-
-**Or from a clone (no npm needed):**
+Once linked/installed, the command is just **`agentainer`**. `tmux` is the only
+external runtime. `node` is required for the npm bin wrapper. PyYAML is used *if
+present*; a bundled `minyaml` parser keeps everything working without it.
 
-```bash
-git clone https://github.com/mehmetcanfarsak/AgentSwarm.git && cd AgentSwarm
-./agentainer --help      # same commands as the global `agentainer`, straight from the repo
-```
+## 🚀 Quick start (no API keys)
 
-## <span id="quickstart"></span>⚡ Quickstart
+The bundled quickstart uses `bash` loop "mock agents" so you can watch the
+mailroom route mail safely:
 
 ```bash
-cp agents.example.yaml agents.yaml
-
-agentainer validate      # parse the config, print the resolved swarm, launch nothing
-agentainer up            # create dirs, install hooks, start tmux, send first prompts
-agentainer status        # who is running
-agentainer attach developer
-agentainer down          # stop everything
+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
 ```
 
-Give the swarm its actual work:
-
-```bash
-agentainer send --to orchestrator "Build a CLI that converts CSV to Parquet."
-```
-
-Watch the traffic between agents:
-
-```bash
-agentainer logs -f              # whole swarm, live
-agentainer logs reviewer -n 20  # one agent
-agentainer inbox developer      # messages an agent received
-```
-
-`agentainer status` gives you the whole swarm at a glance — who is up, who is mid-turn, and how deep each queue is:
+To run real agents, swap each `command` for the actual CLI you installed and drop
+`capture: none` so turns get detected.
 
 <p align="center">
-  <img alt="agentainer status output: a table of agents with their type, state, turn, queue depth, capture mode, and can_talk_to permissions" src="https://raw.githubusercontent.com/mehmetcanfarsak/AgentSwarm/main/assets/screenshot-status.svg" width="820">
+  <img src="https://raw.githubusercontent.com/mehmetcanfarsak/Agentainer/main/assets/demo.svg" alt="Terminal cast of the Agentainer quickstart: up, status, send, then logs showing the mailroom routing mail between mock agents" width="700"/>
 </p>
 
----
-
-## <span id="faq"></span>❓ FAQ
-
-**What is Agentainer?**
-Agentainer is a zero-dependency multi-agent orchestrator that runs a team of AI coding agents — Claude Code, OpenAI Codex, Google's Gemini CLI, and Hermes — in isolated tmux sessions, each with its own working directory, and routes messages between them under a configurable access-control list. You describe the whole team in one YAML file and start it with a single command.
-
-**Which AI coding agents does Agentainer support?**
-Claude Code (`claude`), OpenAI Codex (`codex`), Google's Gemini CLI (`gemini`), and Hermes (`hermes`) out of the box. You can also define your own agent type via `agent_types:` — any CLI that takes input on stdin/tty works, with `capture: pane` or `capture: none`.
-
-**Does Agentainer need Docker or any runtime dependencies?**
-No. It is stdlib-only: Python 3, bash, and tmux. PyYAML is used if present, but a bundled parser handles the config without it. Node is only needed for the global `npm` launcher — running `./agentainer` from a clone needs no Node at all.
-
-**How do I run multiple coding agents together?**
-Write a YAML config listing your agents (and who may talk to whom), then run `agentainer up`. It creates a folder and a tmux session per agent, installs a turn-completion hook, launches each CLI, and types in the first prompt. `agentainer send --to <agent> "…"` messages any agent; `agentainer validate` previews the resolved swarm without launching anything.
-
-**Can agents communicate with each other, and how is that controlled?**
-Yes. Agents exchange tagged `<swarm-message>` / `<swarm-send>` blocks. Messaging is a whitelist: an agent may only reach the agents in its `can_talk_to` list (`"*"` means everyone else); anything else is refused. Auto-forwarding (`forward_responses_to`) can relay finished turns hands-free, bounded by a hop count to prevent loops.
-
-**How do I resume a swarm after a crash or reboot?**
-Each finished turn records the agent's conversation id in `.swarm/sessions.yaml`. `agentainer up --resume` reattaches every agent to its own conversation instead of starting cold, keeping any queued mail. Claude resumes with `--resume <id>`, Codex with `resume <id>`; Gemini and Hermes have no recoverable session id and always start fresh (with a warning).
-
-**Is it safe to let agents run unattended?**
-Agents run with whatever privileges their CLI is launched with. Flags like `claude --dangerously-skip-permissions`, `codex --yolo`, and `gemini --yolo` let them act without confirmation, which is usually what you want for an unattended swarm — so point `root` at a disposable directory and never run a swarm over a checkout you can't afford to lose.
-
-**How is Agentainer different from just opening several terminals?**
-It automates the brittle parts: detecting when each turn finishes (via a Stop/notify hook for Claude/Codex, or pane polling for Gemini/Hermes), typing multi-line prompts reliably into a live TUI, pre-trusting folders so the "trust this directory?" modal doesn't eat the first prompt, enforcing the comms ACL, queueing messages to busy agents, and resuming conversations after a restart.
+## 📬 The model in one screen
 
----
-
-## <span id="how-it-works"></span>🔧 How It Works
-
-**One folder + one tmux session per agent.** Agent `developer` gets
-`workspace/developer/` and a tmux session named `developer` (plus any
-`session_prefix`). The agent's CLI is launched inside that folder, so its file
-operations are naturally scoped to it.
-
-### Working directories
-
-By default every agent gets a fresh folder under `root`, created for you. You can
-override that per agent, or for the whole swarm via `defaults`:
+An agent's entire world is **two verbs** (read a file, write a file) and **four
+folders**:
 
-```yaml
-swarm:
-  root: ./workspace
-  create_workdirs: true          # auto-create missing folders (default)
-
-agents:
-  - name: developer              # -> ./workspace/developer  (created)
-
-  - name: reviewer
-    workdir: ~/projects/acme-api # -> an existing checkout
-    create_workdir: false        # ...and fail loudly if it is not there
-
-  - name: scribe
-    workdir: "{root}/{name}-notes"   # {name} {root} {swarm} {type}
-```
+| 📁 Folder | 📝 Meaning |
+| --- | --- |
+| 📥 `inbox/` | The **one** current unread message (orchestrator releases one at a time). |
+| 📤 `outbox/<name>/` | Write a file 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. |
 
-- **`workdir`** may be absolute, relative to the config file, or use `~`.
-- **`create_workdir: false`** turns a missing folder into an error instead of a
-  new empty directory — the right setting when you are pointing agents at real
-  repositories, where a typo should not silently create `~/projcets/acme-api`.
-- **`defaults.workdir`** applies to every agent that does not override it. With
-  a `{name}` placeholder it lays out a folder each; without one, every agent
-  shares a single directory.
-- **Sharing is allowed and sometimes the point** (a driver and a navigator in one
-  checkout), but agents then overwrite each other's files and interleave commits,
-  so `validate` and `up` warn when it happens. See
-  [`examples/existing-repo.yaml`](examples/existing-repo.yaml).
-- `root` is still used even when every agent lives elsewhere: it holds `.swarm/`
-  with the logs, inboxes and the `swarm` shim.
-
-**Prompts are typed in, not piped.** `swarm up` drops each first prompt into the
-agent's input box with a tmux bracketed paste, as one block, then presses Enter.
-That is why multi-line prompts survive intact instead of being submitted line by
-line.
-
-Getting that to work reliably against a live TUI took more than a sleep:
-
-- **Claude Code silently discards keystrokes for several seconds partway through
-  startup.** Measured on v2.1.205: input at t=2s landed, t=6s and t=12s vanished,
-  t=20s landed. A fixed `boot_delay_ms` is therefore a coin flip. Before typing,
-  Agentainer types a throwaway token and waits for the input box to echo it back,
-  then erases it (`ready_probe`). Enter is never sent, so nothing is submitted.
-- **Readiness is not monotonic**, so after pasting, Agentainer checks that the
-  text actually appeared on screen before pressing Enter, and retries if it did
-  not. If delivery cannot be confirmed it refuses to press Enter, rather than
-  submitting a half-delivered prompt.
-- **Both CLIs open a "do you trust this folder?" modal** on first run in a new
-  directory, which would eat the first prompt (Enter answers the dialog). Claude
-  does this even under `--dangerously-skip-permissions`. Agentainer pre-trusts each
-  agent's workdir: for codex in its generated `config.toml`, for claude by adding
-  `hasTrustDialogAccepted` for that path in `~/.claude.json`.
-- **Both collapse a long paste into a chip** rather than showing the text —
-  `[Pasted text #1 +36 lines]` for claude, `[Pasted Content 2580 chars]` for codex.
-  Delivery verification recognises both.
-
-**Agents talk in tagged messages.** A message arrives inside an envelope, so the
-agent always knows where it starts, where it ends, and who sent it:
+When an agent **stops** with unread mail, the orchestrator sweeps its `outbox`
+and pastes a **nudge** ("you have mail — read it, then move it to `read/`"),
+re-injecting the protocol every time (including the allowed-recipient list).
 
-```
-<swarm-message from="lead" to="reviewer" id="m-eb4105" reply-to="m-3f9a1c">
-Review finding for ./parse: tokenize() mishandles a trailing backslash.
-
-    printf 'a\' | ./parse
-</swarm-message>
-```
-
-To send one, the agent simply **writes a block in its reply**. The capture hook
-reads it when the turn ends and delivers it — no shell, no quoting, so multi-line
-bodies, code blocks and backslashes survive intact:
-
-```
-<swarm-send to="reviewer" reply-to="m-3f9a1c">
-Please review src/parse.py.
-
-    printf 'a\' | ./parse
-</swarm-send>
-```
+## 🏗️ Architecture
 
-`<swarm-broadcast>` (no `to`) reaches everyone the sender may talk to. The `id`
-and `reply-to` attributes let agents thread a conversation instead of guessing
-which question an answer belongs to. Set `message_format: plain` to go back to the
-old `[swarm] message from <sender>:` header, and `parse_outbound_tags: false` to
-stop reading tags out of replies.
+<a href="https://raw.githubusercontent.com/mehmetcanfarsak/Agentainer/main/assets/architecture.svg">
+  <img src="https://raw.githubusercontent.com/mehmetcanfarsak/Agentainer/main/assets/architecture.svg" alt="Agentainer architecture: agentainer.yaml drives a CLI core that opens one tmux session per agent; agents read and write mail files that the orchestrator routes" width="720"/>
+</a>
 
-Agents can also send from their shell, which is useful mid-task rather than at the
-end of a turn (but then they must quote the text themselves):
-
-```bash
-swarm send --to reviewer "I finished the parser, please review src/parse.py"
-swarm broadcast "heads up: I renamed the config module"
-```
-
-Either way the message is permission-checked against `can_talk_to`, archived under
-`.swarm/inbox/<recipient>/`, and written to the event log.
-
-The raw tmux equivalent also works, and bypasses permissions and logging:
-
-```bash
-tmux send-keys -t reviewer -l "your message" && tmux send-keys -t reviewer Enter
-```
-
-**Agents get reminded when their answer goes nowhere.** A model that was asked a
-question will often just *write the answer as prose* and end its turn — and that
-prose reaches nobody, because only a `<swarm-send>` block is delivered. So when an
-agent owes a reply and finishes a turn without sending one, Agentainer messages it:
-
-```
-Your last turn sent no message to anyone, and lead is waiting on your answer to
-message m-c73724.
-...
-<swarm-send to="lead" reply-to="m-c73724">
-your answer here, over as many lines as you need
-</swarm-send>
-```
-
-If instead the agent *tried* to send but the block was malformed, it gets the
-specific diagnosis — unclosed tag, missing `to`, unknown recipient, permission
-denied — so it can correct itself rather than lose the message silently.
-
-It is reminded at most `max_reply_reminders` times (default **1**), then Agentainer
-gives up and stops nagging. An agent that auto-forwards via `forward_responses_to`
-is never reminded, since its words did reach someone. Turn it off per agent with
-`reply_reminder: false`.
-
-**Conversations survive a restart.** Each time an agent finishes a turn, its
-conversation id is written to `<root>/.swarm/sessions.yaml`:
-
-```yaml
-agents:
-  lead:
-    session_id: "0c2e47e2-5110-4e69-ae45-69d8492d2084"
-    type: "claude"
-    transcript: "/root/.claude/projects/.../0c2e47e2-....jsonl"
-    updated_at: "2026-07-09T21:00:41+00:00"
-```
-
-If the machine dies, `swarm up --resume` reattaches every agent to its own
-conversation instead of starting a fresh one — it does not re-send the first
-prompt, and it keeps any mail still queued for that agent:
-
-```bash
-agentainer sessions          # what is recorded, and the command that would resume it
-agentainer up --resume       # reattach; agents without a recorded id start fresh
-```
-
-Claude is resumed with `--resume <id>`, codex with `resume <id>`. Set
-`swarm.resume: true` to make it the default, and `--no-resume` to override.
-Gemini and hermes have no recoverable session id (their turns are scraped from
-the terminal), so they always start a fresh conversation, with a warning.
-
-If your command runs the CLI through an alias or wrapper, flags cannot simply be
-appended — give the full recipe:
-
-```yaml
-- name: lead
-  command: "bash -ic chy3"
-  resume_command: "bash -ic 'chy3 --resume {session_id}'"
-```
-
-**Permissions are a whitelist.** An agent may only message the agents in its
-`can_talk_to` list. Anything else is refused with an explanatory error that the
-agent sees on its own terminal. Use `can_talk_to: "*"` for "everyone else".
-
----
-
-## <span id="capturing-what-an-agent-says"></span>🎬 Capturing What An Agent Says
-
-Agentainer needs to know when an agent finishes a turn — both to log it and to
-support auto-forwarding. How it finds out depends on the CLI, and the two
-mechanisms are **not** equally good:
-
-| `capture` | Used by | Mechanism | Reliability |
-|---|---|---|---|
-| `hook` | `claude`, `codex` | The CLI runs a program when a turn completes | Exact — the model's final message |
-| `pane` | `gemini`, `hermes` | Poll the tmux pane, diff it once it stops changing | Heuristic — sees rendered text |
-| `none` | any | Nothing is captured | — |
-
-- **claude** → a `Stop` hook is written into `<agent-dir>/.claude/settings.json`,
-  with **no `matcher` key** (`Stop` is not a tool event, and supplying one stops the
-  interactive TUI from ever running the hook). It reads the session transcript.
-  Claude fires the hook *before* flushing the assistant message to that transcript,
-  so Agentainer polls it briefly, and only reads text written after the last user
-  message — otherwise a turn would silently capture nothing, or re-relay the
-  previous turn's reply.
-- **codex** → the agent gets a private `CODEX_HOME` at `<agent-dir>/.codex/`
-  with a `notify` program wired up (your `~/.codex/auth.json` is symlinked in, so
-  it stays logged in, and your existing `config.toml` is carried over). The
-  generated file keeps `notify` above every `[table]` header -- TOML is
-  order-sensitive, and a `notify` written after one silently becomes
-  `projects.<dir>.notify`, which codex never calls.
-- **gemini / hermes** → no turn-completion hook exists, so a background watcher
-  samples the pane and emits the new text once it has been quiet for
-  `pane_idle_ms`. It filters out the terminal's echo of incoming messages, but
-  it is still terminal scraping: spinners and redraws can leak in. Prefer having
-  these agents call `swarm send` explicitly.
-
-Set `capture:` per agent to override the default for its type.
-
-### <span id="subagents-parallel-work-and-busy-agents"></span>🧩 Subagents, parallel work, and busy agents
-
-Coding agents spawn subagents and background tasks. Four things follow from that.
-
-**A subagent that calls `swarm send` speaks as its parent.** Subagents inherit the
-agent's environment, so `SWARM_AGENT` still names the parent and `can_talk_to` is
-enforced against the parent. That is almost always what you want: the swarm sees
-one `developer`, not five anonymous workers.
-
-**Parallel subagents cannot garble each other.** A paste and the Enter that submits
-it are two separate tmux calls, so two senders racing on one pane used to produce
-one Enter submitting two concatenated messages and another submitting nothing.
-Everything that types into a pane now takes a per-recipient lock, so concurrent
-sends queue up instead of interleaving. Different recipients are still messaged in
-parallel.
-
-**A message that arrives while an agent is busy is queued, not lost.** The CLIs
-hold it in their input box and process it when the current tool call finishes —
-codex says so out loud (`Messages to be submitted after next tool call`).
-
-**An agent that ends its turn saying "I'll respond when the subagent finishes"
-gets captured twice.** With `capture: hook`, the Stop/notify hook fires when the
-*agent's* turn ends. Claude's `Task` subagents run inside the turn, so the hook
-waits for them. But work the agent genuinely backgrounds lets the turn end early,
-and then:
-
-- that interim message is captured, and forwarded if `forward_responses_to` is set;
-- when the agent is re-invoked and finishes for real, its answer is captured and
-  forwarded too. The hop counter records the hop at which the agent *received* its
-  last message, so a second response does not consume an extra hop — the real
-  answer is never suppressed by the loop guard.
-
-Subagent chatter never leaks: Claude writes subagent turns into the same transcript
-marked `isSidechain: true`, and the hook skips them, so what gets relayed is the
-agent's own final message rather than whatever a subagent happened to say last.
-
-With `capture: pane` (gemini, hermes) this breaks down. A quiet pane is the only
-"turn finished" signal there is, so a pause while a subagent works looks exactly
-like a completed turn: the interim "I'll respond when it finishes" is captured and
-forwarded, then the real answer is captured separately. Raise `pane_idle_ms` above
-the longest silence you expect, or set `capture: none` and have the agent call
-`swarm send` when it actually has something to say.
-
-### Busy agents and backpressure
-
-If `b` gives `a` a task, `a` is mid-turn. When `c` then tries to task `a` as well,
-the message is refused rather than dropped into a working agent's input box:
-
-```
-$ swarm send --to a "please review my diff"
-xx a is busy right now (working for 42s on a task from b). Please try again after
-   some time, or put your message in the queue and wait for the answer:
-     swarm send --to a --queue "..."   # delivered automatically when a is free
-     swarm send --to a --wait "..."    # block here until a is free
-   Meanwhile you are free to do other work.
-```
-
-So `c` chooses: come back later, `--queue` it and carry on with other work, or
-`--wait` and block. A queued message is delivered by the next capture hook that
-fires for `a`, the moment it goes idle. Agents are told all of this in the
-communication block appended to their first prompt.
-
-```bash
-swarm status          # TURN column: idle / busy 42s / untracked, plus QUEUE depth
-swarm queue a         # what is waiting for a, and who sent it
-swarm queue a --clear # drop it all
-swarm idle a          # force a back to idle, then drain -- if a capture never fired
-```
-
-**This is safe against parallel senders.** The busy check and the "now busy" write
-happen inside the same per-recipient lock as the paste, so two subagents racing to
-message an idle agent cannot both pass the check — one delivers, the other is told
-it is busy. A flag checked and set separately would let both through.
-
-Some honest limits:
-
-- Busy tracking needs a "turn finished" signal, so it only works for agents with
-  `capture: hook` or `capture: pane`. A `capture: none` agent reports `untracked`
-  and always accepts mail.
-- With `capture: pane`, "idle" means "the pane went quiet", which a thinking agent
-  can also look like. Backpressure there is a hint, not a guarantee.
-- A turn started by a human typing directly into the pane is not tracked.
-- If a capture never fires (crashed CLI, misconfigured hook), the agent would look
-  busy forever. After `busy_timeout_ms` (default 15 minutes) it is treated as idle
-  again, with a warning. `swarm idle <agent>` clears it immediately. Any mail queued
-  for such an agent is not lost either: whenever some *other* agent finishes a turn,
-  Agentainer sweeps the now-idle agent's queue and delivers what was stranded — so
-  one missed turn-completion cannot wedge a queue permanently.
-- A capture only fires if the agent's `type` matches the CLI its `command` actually
-  runs. If you point a `type: codex` agent at a `claude` command (e.g. through an
-  alias), it gets codex's `notify` hook, which claude never calls — its turns are
-  never detected and it looks busy forever. Set `type` to whatever the command runs.
-- `--force` and `--ignore-busy` deliver anyway. The agent's CLI will queue the
-  message and handle it after the current tool call, so nothing is lost — you just
-  give up the backpressure.
-
-### Auto-forwarding
-
-`forward_responses_to` relays an agent's finished turn to other agents without
-it having to ask:
-
-```yaml
-- name: researcher
-  can_talk_to: [orchestrator, developer]
-  forward_responses_to: [orchestrator]   # must be a subset of can_talk_to
-```
-
-Two agents forwarding to each other would ping-pong forever, so every forwarded
-message carries a hop count, and forwarding stops at `max_forward_hops`
-(default 3). A fresh message from you resets the count. Auto-forwarding is
-powerful but chatty — for most swarms it is better to let agents decide when to
-speak, and leave `forward_responses_to` unset.
-
----
+<details>
+<summary>Plain-text architecture (for terminals &amp; screen readers)</summary>
 
-## <span id="configuration-reference"></span>⚙️ Configuration Reference
-
-Full annotated example: [`agents.example.yaml`](agents.example.yaml).
-Machine-readable summary for agents: [`llms.txt`](llms.txt).
-
-### `swarm:`
-
-| Key | Default | Meaning |
-|---|---|---|
-| `name` | config filename | Label used in prompts and logs |
-| `root` | `./workspace` | Where per-agent folders are created |
-| `create_workdirs` | `true` | Auto-create missing agent folders |
-| `session_prefix` | `""` | Prepended to every tmux session name |
-| `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, a stuck "busy" agent is treated as idle |
-| `message_format` | `tagged` | `tagged` XML-ish envelopes, or `plain` text headers |
-| `max_reply_reminders` | `1` | How often to remind an agent that its reply reached nobody |
-| `resume` | `false` | Make `up` reattach to recorded conversations by default |
-| `pane_idle_ms` | `2500` | Quiet time before a `pane` turn counts as done |
-| `pane_poll_ms` | `700` | Pane sampling interval |
-| `pane_scrollback` | `400` | Lines of scrollback the watcher diffs |
-| `tmux_history_limit` | `50000` | Scrollback kept per agent pane so you can scroll up (`0` = tmux default) |
-| `tmux_mouse` | `true` | Enable mouse-wheel scrolling in the panes |
-
-### `agents:`
-
-| Key | Default | Meaning |
-|---|---|---|
-| `name` | *required* | Folder name **and** tmux session name |
-| `type` | `claude` | `claude`, `codex`, `gemini`, `hermes`, or one you define |
-| `command` | from type | Exact CLI to run, e.g. `claude --dangerously-skip-permissions` |
-| `can_talk_to` | `[]` | Whitelist of agents it may message; `"*"` for all others |
-| `first_prompt` | `""` | Prompt typed in after the CLI boots |
-| `first_prompt_file` | — | Read the prompt from a file instead |
-| `append_agents_that_you_can_talk_to_prompt` | `true` | Append the "here's who you can message and how" block |
-| `in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt` | `false` | Append "stand by, your task is coming next" |
-| `forward_responses_to` | `[]` | Auto-relay finished turns to these agents |
-| `capture` | from type | `hook`, `pane`, `none`, or `auto` |
-| `boot_delay_ms` | from type | Grace period before probing the input box (not a delivery guarantee) |
-| `ready_probe` | `true` | Wait for the input box to echo a token before typing |
-| `busy_check` | `true` | Refuse incoming messages while this agent is mid-turn |
-| `parse_outbound_tags` | `true` | Route `<swarm-send>` blocks the agent writes in its reply |
-| `reply_reminder` | `true` | Remind it when it owes a reply but sent nothing |
-| `resume_args` | from type | Appended to `command` to resume, e.g. `--resume {session_id}` |
-| `resume_command` | — | Full replacement command when flags can't be appended |
-| `workdir` | `<root>/<name>` | Override the agent's directory (`~`, `{name}`, `{root}`, `{swarm}`, `{type}`) |
-| `create_workdir` | from `create_workdirs` | Create the folder if missing, else error |
-| `env` | `{}` | Extra environment variables for its tmux session |
-
-### `agent_types:`
-
-Override a built-in launch command, or define a new agent type:
-
-```yaml
-agent_types:
-  claude:
-    command: "claude --dangerously-skip-permissions --model opus"
-  aider:                       # a type of your own
-    command: "aider --yes"
-    capture: pane              # only claude/codex support `hook`
-    boot_delay_ms: 4000
 ```
-
-### `defaults:` and `templates:`
-
-`defaults:` supplies any agent key for agents that don't set it, including
-`workdir` — useful for putting a whole swarm in one repository. `templates:`
-overrides the text Agentainer generates — `comms` and `task_notice` (appended to
-first prompts), plus `reply_reminder` and `send_failed` (the nudges) —
-with `{agent} {swarm} {peers} {prefix} {inbox} {workdir}` available as
-placeholders.
-
----
-
-## <span id="examples"></span>🧪 Examples
-
-Ready-to-run swarms in [`examples/`](examples/):
-
-| File | Shape | Shows off |
-|---|---|---|
-| [`research-swarm.yaml`](examples/research-swarm.yaml) | Hub and spoke | A lead delegating to a scout, an analyst and a writer; a custom output folder |
-| [`software-company.yaml`](examples/software-company.yaml) | Org chart | Six agents across all four CLIs, with a deliberately restricted comms graph |
-| [`bug-hunt.yaml`](examples/bug-hunt.yaml) | Pipeline | `forward_responses_to` chaining reproduce → diagnose → fix → verify, hands-free |
-| [`existing-repo.yaml`](examples/existing-repo.yaml) | Pairing | Two agents in one **existing** checkout, with `create_workdirs: false` |
-| [`red-team.yaml`](examples/red-team.yaml) | Adversarial triad | Attacker vs defender arbitrated by a referee, over one **existing** checkout |
-| [`debate.yaml`](examples/debate.yaml) | Debate + judge | Two advocates argue opposite sides; a judge cross-examines and rules |
-| [`writers-room.yaml`](examples/writers-room.yaml) | Hub + review cycle | An editor driving a writer, fact-checker and critic to a finished article |
-| [`incident-response.yaml`](examples/incident-response.yaml) | Incident hub | A commander coordinating investigator/responder/scribe under time pressure |
-| [`tdd-pingpong.yaml`](examples/tdd-pingpong.yaml) | Tight 2-agent loop | Tester writes one failing test, coder makes it pass, in one shared repo |
-| [`brainstorm.yaml`](examples/brainstorm.yaml) | Diverge + converge | Three angled idea-generators fanning out, then a synthesiser ranks them |
-| [`localization.yaml`](examples/localization.yaml) | Pipeline | Translate → review → back-check, auto-forwarded via `forward_responses_to` |
-| [`multi-language-broadcast.yaml`](examples/multi-language-broadcast.yaml) | Broadcast fan-out | One translator broadcasts a source to N language reviewers; a consolidator compiles and broadcasts back |
-| [`code-review-broadcast.yaml`](examples/code-review-broadcast.yaml) | Broadcast hub | One PR broadcast to specialist reviewers (correctness/security/perf); each replies to the coordinator who synthesizes |
-| [`ping-pong.yaml`](examples/ping-pong.yaml) | Round-robin | Two agents trade a unit of work, each broadcast naming who is up next (distinct from tdd-pingpong's fixed `forward_responses_to`) |
-
-```bash
-agentainer validate -c examples/research-swarm.yaml   # look before you leap
-agentainer up       -c examples/research-swarm.yaml
-agentainer send --to lead "Research the state of WebGPU compute shaders."
+agentainer.yaml  ──▶  agentainer up  ──▶  one tmux session + workdir per agent
+ (agents +                (CLI core              │
+  can_talk_to)            + supervisor)           ▼
+                          │                agents READ inbox/  WRITE outbox/<name>/
+                          │                       │                │
+                          │                       ▼                ▼
+                          │                orchestrator routes the mail:
+                          │                ACL check, message ID, read-state,
+                          │                queue, durable JSONL log
+                          ▼
+                   liveness supervisor heartbeat
+                   (reconciles stale-busy / dead / silent-but-alive)
 ```
+</details>
 
-`existing-repo.yaml` intentionally refuses to start until you point `workdir` at
-a repository that exists.
-
-## <span id="commands"></span>💻 Commands
-
-| Command | Purpose |
-|---|---|
-| `agentainer up` | Start the swarm. `--only a,b`, `--restart`, `--resume`, `--no-prompt`, `--attach` |
-| `agentainer down` | Kill sessions and watchers. `--only a,b` |
-| `agentainer restart` | `down` then `up` |
-| `agentainer status` | Table of agents, sessions, capture mode, permissions |
-| `agentainer attach <agent>` | Attach to an agent's tmux session |
-| `agentainer send --to <agent> "msg"` | Deliver a message (`--from`, `--file`, `--queue`, `--wait`, `--ignore-busy`, `--force`) |
-| `agentainer broadcast "msg"` | Message everyone the sender may talk to |
-| `agentainer sessions` | Show each agent's recorded conversation id (`--raw`) |
-| `agentainer queue <agent>` | Show what is waiting for a busy agent (`--clear`) |
-| `agentainer idle <agent>` | Force an agent back to idle, then drain its queue |
-| `agentainer inbox <agent>` | Print archived messages |
-| `agentainer logs [agent] [-f]` | Event log: prompts, responses, messages |
-| `agentainer validate` | Parse the config. `--show-prompts` renders final prompts |
-
-`agentainer my-swarm.yaml` is shorthand for `agentainer up -c my-swarm.yaml`.
-`-c` and `$SWARM_CONFIG` both select a config; `-c` wins.
-
-## <span id="project-layout"></span>📁 Project Layout
+## 🛠️ Commands
+
+| 🛠️ Command | 📝 Purpose |
+| --- | --- |
+| 🔍 `validate` | Resolve and print the config; launch nothing. |
+| 🆙 `up` | Create dirs + mailbox folders, install per-type turn-detection, open one tmux session per agent. |
+| 🔌 `down` | Tear the swarm down. |
+| 🔁 `restart` | Down then up. |
+| 📡 `status` | Show agent/health summary. |
+| 🔗 `attach` | Attach to an agent's tmux session. |
+| ✉️ `send` | Send a `user` message into the swarm (`--to <agent>`). |
+| 🗂️ `sessions` | List recorded tmux sessions (resume info). |
+| ⏳ `queue` | Show pending mail per agent. |
+| 😴 `idle` | List agents currently idle. |
+| 📨 `inbox` | Show current inbox message per agent. |
+| 📟 `logs` | Tail the durable JSONL event log (`-f` to follow). |
+| 🪝 `hook` | Turn-completion entry point (called by `claude`/`codex` stop hooks). |
+| 👀 `watch` | Live-watch the supervisor. |
+| 💗 `supervise` | Run one (or the loop of) supervisor tick(s). |
+| 👤 `user` | Toggle `user` availability. |
+| 🌐 `serve` | Serve the mail-app control-plane UI (threads, settings/agent editing, availability, direct-to-pane) on `127.0.0.1`. |
+| ➕ `add` | Add an agent to the config (YAML) and bring it up immediately. |
+| 🗑️ `remove` | Remove an agent from the config and stop its session. |
+| ✏️ `edit` | Edit an agent's fields in the config (`-s key=value`, repeatable) and reconcile. |
+| 🔧 `reconcile` | Start agents missing from the running set / stop sessions no longer configured. |
+
+See `llms.txt` for a machine-readable summary and `ProjectPlan.md` for the full
+design (source of truth).
 
-```
-AgentSwarm/
-├── agentainer                # entrypoint
-├── agents.example.yaml     # annotated config
-├── llms.txt                # reference for agents configuring this tool
-├── hooks/
-│   ├── claude_stop.sh      # Claude Code Stop hook
-│   └── codex_notify.sh     # Codex notify program
-├── lib/
-│   ├── swarm.py            # tmux orchestration, routing, capture
-│   ├── config.py           # schema, defaults, validation
-│   └── minyaml.py          # YAML subset parser, used when PyYAML is absent
-├── tests/validate.sh       # full suite: mock agents, no model calls
-├── examples/               # research, software company, bug hunt, pairing, red team, debate, writers' room, incident, tdd, brainstorm, l10n, multi-language + code-review (broadcast), ping-pong (round-robin)
-└── workspace/              # created by `up`
-    ├── <agent>/            # one folder per agent
-    └── .swarm/
-        ├── state.json      # what `up` started
-        ├── sessions.yaml   # each agent's conversation id, for `up --resume`
-        ├── bin/swarm       # the `swarm` command agents call
-        ├── logs/           # <agent>.jsonl + swarm.jsonl
-        ├── inbox/<agent>/  # archived messages
-        └── run/            # watcher pids, hop counters
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mehmetcanfarsak/Agentainer/main/assets/screenshot-status.svg" alt="Terminal output of agentainer status and agentainer queue against a running mock swarm" width="700"/>
+</p>
 
-## <span id="tests"></span>✅ Tests
+## 🔒 Key invariants
+
+- 🪶 **Zero runtime dependencies, forever** — Python 3 + bash + tmux; bundled
+  `minyaml` fallback; stdlib-only UI (P2+).
+- 🤝 **`can_talk_to` is cooperative, not an OS boundary** — enforced for
+  well-behaved agents, documented honestly (Decision D15).
+- 📛 **`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 (TUIs keep no
+  scrollback).
+- 🧪 **100% line coverage** via mock agents (bash loops, no API keys).
+
+## 🖥️ The control-plane UI (P2–P3)
+
+`agentainer serve -c my-swarm.yaml --port 8080 --token <secret>` starts a
+**zero-dependency** web UI (stdlib `http.server` + a single vanilla-JS page, no
+framework, no build step). It binds `127.0.0.1` by default; any non-loopback bind
+requires a token. The UI is a control plane, so keep it on loopback unless a
+token is supplied.
+
+It is a **modern, mobile-friendly mail app** for the swarm:
+
+- **Agents overview** — a card per agent with its role, type, and live
+  running/idle/busy/unread/queue status.
+- **Mail view** — click an agent to open its correspondence. The left rail lists
+  its contacts (the `user`, its peers, `system`) instead of mail folders; pick
+  one and every message between the two is reconstructed into a threaded
+  conversation (rendered as **markdown**), each with its **delivery status**
+  (waiting → delivered → read). Reply to an agent **as the `user`** inline.
+- **Activity + topology** — a global event timeline and a who-talks-to-whom graph.
+- **Direct to the session** — watch each agent's **live tmux pane** and type
+  straight into it (bypassing the mailroom) when you need to.
+- **Availability toggle** — flip whether the `user` is available to receive mail
+  (off by default: mail is *held*, never bounced) right from the top bar; the
+  change is persisted to `agentainer.yaml`.
+- **Settings & agents** — edit swarm settings and **add / edit / delete agents**
+  from the UI; every change is written back to `agentainer.yaml` (via the same
+  stdlib emitter, so it works with **or without** PyYAML).
+- **Telegram bridge** *(optional)* — configure a bot token + chat id in Settings
+  to **mirror** the swarm's mail (all agents or a selected set, plus your own
+  mail) to a Telegram chat, and **reply from your phone**: a Telegram message
+  reply routes back into the swarm as `user` mail. Stdlib `urllib` only — no new
+  dependency; the mirror is best-effort so the network can never stall routing.
+
+## 🔄 Dynamic reconcile (P4)
+
+No need to tear the whole swarm down to change it:
 
 ```bash
-tests/validate.sh
+agentainer add    dave --type codex --command "codex" --can-talk-to "alice,user" -c my-swarm.yaml
+agentainer edit   alice -s can_talk_to="dave,user" -c my-swarm.yaml
+agentainer remove bob -c my-swarm.yaml
+agentainer reconcile -c my-swarm.yaml      # start missing agents, stop orphaned sessions
 ```
 
-48 checks over the real code paths — tmux, hooks, locks, queues, the tag parser,
-sessions and resume — driven by mock agents, so it needs no API key and costs
-nothing. It covers the awkward cases: the check-and-set race between concurrent
-senders, a queued message beating a reply reminder, a subagent's sidechain turn
-being skipped, and a transcript read before Claude has flushed it.
-
-## <span id="troubleshooting"></span>🛠️ Troubleshooting
-
-**"could not confirm the text arrived; NOT pressing Enter".** The agent's input
-box never echoed the prompt, so Agentainer refused to submit it. Attach to the
-session to see what state the CLI is in -- usually a modal (login, trust,
-onboarding) is holding focus. Raise `ready_timeout_ms` if the CLI is merely slow.
-
-**An agent says it "cannot message" another.** That is the permission check
-doing its job — add the recipient to the sender's `can_talk_to`.
-
-**A `pane` agent forwards garbage.** Terminal scraping picked up a redraw. Raise
-`pane_idle_ms`, or set `capture: none` and instruct the agent to call
-`swarm send` itself.
-
-**Forwarding stopped with a hop-limit warning.** Two agents were relaying to each
-other. Raise `max_forward_hops`, or break the cycle in `forward_responses_to`.
-
-**Nothing captured from a claude agent.** Check `<agent-dir>/.claude/settings.json`
-exists and `.swarm/logs/hooks.log` for errors. If the agent also looks busy forever,
-its `type` probably does not match the CLI its `command` runs (see the capture note
-under [Busy agents](#subagents-parallel-work-and-busy-agents)).
-
-**Can't scroll up in an attached session.** Agentainer raises tmux's scrollback to
-`tmux_history_limit` (50000 lines) and turns on `tmux_mouse`, so the wheel scrolls
-the backlog; press `q` to leave copy mode. If your terminal grabs the wheel itself,
-use `Ctrl-b [` then PageUp. Both options are set on the tmux server before sessions
-are created, so a server that was already running keeps its old panes' smaller
-buffer — restart the swarm (or that pane) to pick up the larger one.
-
-## <span id="a-note-on-flags"></span>⚠️ A Note On Flags
-
-`claude --dangerously-skip-permissions`, `codex --yolo` and `gemini --yolo` let
-agents act without asking for confirmation. That is usually what you want for an
-unattended swarm, and it means several models are running tools unsupervised in
-these directories. Point `root` somewhere disposable, and don't run a swarm over
-a directory you can't afford to lose.
-
----
-
-## 🤝 Contributing
-
-Pull requests and issues are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for
-the zero-dependency principles, a key-free smoke test, and the PR checklist. A
-safe first run with no API keys lives in [quickstart.yaml](quickstart.yaml).
+`add`/`remove`/`edit` rewrite `agentainer.yaml` with a stdlib-only YAML emitter
+(works with **or without** PyYAML) and then `reconcile` the change into effect.
+
+## 📊 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, driven entirely by
+mock agents (no API keys).
+
+## ❓ FAQ
+
+**🤖 What is Agentainer?**
+Agentainer is a zero-dependency orchestrator that runs several AI coding agents
+(Claude Code, Codex, Gemini, Hermes) at once, each in its own `tmux` session and
+working directory. Instead of agents exchanging messages inside their chat prose,
+they communicate through a **file-based mail model**: an agent receives mail by
+reading a file in its `inbox/` and sends mail by writing a file into
+`outbox/<name>/`. The orchestrator owns all the hard logic — routing, access
+control, message IDs, retries, and the durable log — so the agents only deal with
+plain natural-language files.
+
+**🧩 Which AI coding agents does Agentainer support?**
+Claude Code (`type: claude`), OpenAI Codex (`type: codex`), Google Gemini CLI
+(`type: gemini`), and Hermes (`type: hermes`). Turn-completion detection is wired
+per `type` (a Stop hook for Claude, a `notify` program for Codex, and pane polling
+for Gemini/Hermes). Any CLI that can read and write files in a tmux pane can be
+slotted in as a new `type`.
+
+**🐳 Does Agentainer need Docker or any runtime dependencies?**
+No. The entire runtime is Python 3, `bash`, and `tmux` — nothing to `pip install`.
+PyYAML is used *if present*, but a bundled fallback parser (`minyaml`) keeps
+everything working without it, and CI proves that no-PyYAML path. `node` is only
+needed for the npm launcher, never at swarm runtime. Docker is optional and not
+required.
+
+**🚀 How do I run multiple coding agents together?**
+Write one `agentainer.yaml` listing each agent, then run `agentainer up -c
+my-swarm.yaml`. That creates the mailbox folders, installs per-type turn detection,
+and opens one tmux session per agent. `agentainer status` shows the swarm;
+`agentainer send --to <agent> "..."` injects a `user` message; `agentainer down`
+tears it all down. The bundled `examples/quickstart.yaml` runs entirely on
+key-free bash-loop mock agents so you can watch the mailroom route mail with no API
+keys.
+
+**💬 Can agents communicate with each other, and how is that controlled?**
+Yes — by writing into each other's `outbox/<name>/` folders. Communication is
+controlled by the `can_talk_to` access-control list in the config: an agent may
+only deliver to names listed there (`"*"` means everyone). The ACL is enforced by
+the orchestrator at routing time — a disallowed send is bounced back as a `system`
+message and filed in `failed/`. It is cooperative, not an OS sandbox (an agent with
+filesystem access *could* bypass it), so it's documented honestly rather than
+presented as a security boundary.
+
+**♻️ How do I resume a swarm after a crash or reboot?**
+`agentainer up --resume -c my-swarm.yaml` reattaches recorded Claude and Codex
+conversations via their native resume commands (`claude --resume <id>`,
+`codex resume <id>`); Gemini and Hermes always start fresh with a warning, since
+they have no resume bridge. Conversation ids are recorded in
+`<root>/.agentainer/sessions.yaml` as each agent finishes its first turn.
+
+**🛡️ Is it safe to let agents run unattended?**
+The design assumes unattended operation. A liveness **supervisor heartbeat**
+(reconciling stale-busy, dead, and silent-but-alive agents) is always running; a
+per-agent health probe catches the "alive but silent" case the supervisor can't
+otherwise see; and several safeguards prevent a wedged agent from stalling the
+swarm — including auto-releasing the next message after N presentations and a
+rate cap on runaway auto-exchanges. That said, agents can run
+`--dangerously-skip-permissions`, so the control-plane UI binds `127.0.0.1` by
+default and requires a token for any remote bind.
+
+**⚖️ How is Agentainer different from just opening several terminals?**
+With several terminals you manually paste prompts, watch for completion, and relay
+messages by hand — and a model that forgets a step silently stalls. Agentainer
+automates the whole loop: it releases exactly one inbox message at a time, detects
+each turn's completion per `type`, sweeps outgoing mail on stop, enforces the
+`can_talk_to` ACL, retries nudges, keeps a durable JSONL event log as the source of
+truth, and runs a supervisor so one stuck agent can't wedge the rest. The models
+only read and write files; all coordination is deterministic orchestrator code.
 
 ## 📜 License
 
-Released under the [MIT License](LICENSE).
+MIT — see [LICENSE](LICENSE).