agentainer 0.1.7 → 2.0.1

package/lib/config.py

@@ -1,4 +1,21 @@
-"""Load, normalise and validate an Agentainer YAML config."""
+"""Load, normalise and validate an Agentainer YAML config.
+
+This is the contract anchor every other module imports. It ports v1's proven
+config loader but adapts the schema to the v2 file-based mail model:
+
+  * the agent's standing instructions are now ``role`` (``first_prompt`` is a
+    deprecated alias);
+  * the XML-envelope comms/reply-reminder machinery is gone -- v2 is plain
+    natural-language mail files read/written by the model;
+  * per-agent ``mail_dir`` selects where the four mailbox folders live, with
+    automatic namespacing when two agents share one workspace (see ``mail_paths``);
+  * ``user``/``system`` are reserved virtual mailboxes, never agent names;
+  * new ``type`` <-> ``command`` mismatch detection prevents the silent-deadlock
+    footgun carried forward from v1.
+
+The orchestrator owns all routing/ACL/state; the model only reads and writes
+natural-language files. See ProjectPlan.md (§4-§16, §24, §29).
+"""
 
 from __future__ import annotations
 
@@ -6,6 +23,7 @@ import os
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
+from types import SimpleNamespace
 from typing import Any
 
 try:  # pragma: no cover - exercised by whichever branch is installed
@@ -30,6 +48,12 @@ class ConfigError(Exception):
     pass
 
 
+# The four real coding-agent CLIs. A `command` that launches a *different* one
+# than `type` implies will never fire its turn-completion signal and wedges the
+# agent. Used by the mismatch detector below. A mock command (e.g.
+# `bash -c 'while true; do read ...'`) contains none of these tokens and passes.
+CLI_TOKENS = ("claude", "codex", "gemini", "hermes")
+
 # Built-in knowledge about each supported coding agent. `capture` says how we
 # learn that the agent finished a turn:
 #   hook  -- the CLI can call an external program on turn completion
@@ -64,137 +88,8 @@ BUILTIN_AGENT_TYPES: dict[str, dict[str, Any]] = {
 
 VALID_CAPTURE = ("hook", "pane", "none", "auto")
 
-VALID_MESSAGE_FORMATS = ("tagged", "plain")
-
 NAME_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_-]*$")
 
-DEFAULT_COMMS_TEMPLATE = """\
----
-## Inter-agent communication protocol
-
-You are the agent **{agent}** on the **{swarm}** team.
-Agents you are allowed to message: {peers}
-
-### Receiving
-
-Messages arrive in your prompt inside a tag, so you can always tell where one
-starts and ends:
-
-    <swarm-message from="SOMEONE" id="m-1a2b3c">
-    the message body,
-    which may span many lines
-    </swarm-message>
-
-Note the `id`. Quote it as `reply-to` when you answer, so the other agent knows
-which of its questions you are answering. Every message is also archived under
-`{inbox}` if you need to re-read one.
-
-### Sending
-
-Sending is a deliberate act, not something every turn needs. **Most of your turns
-will contain no tag at all** -- you think, run commands, and work in your own
-directory in plain text, exactly as you normally would. Write a message block ONLY
-when you actually want to hand something to another agent: a question, a result, or
-a handoff. When you have nothing to send, send nothing.
-
-When you do want to send, write this block **in your reply**. It is read as soon as
-your turn ends, then delivered. Do not escape or quote the body -- write it
-literally, across as many lines as you need:
-
-    <swarm-send to="AGENT_NAME" reply-to="m-1a2b3c">
-    Your message. Multiple lines, code blocks and quotes are all fine.
-    </swarm-send>
-
-To reach everyone you are allowed to talk to, use `<swarm-broadcast>` with no `to`.
-
-The `reply-to` attribute is optional; drop it when you are starting a new thread.
-Quoting it also marks your message as an answer, so the other agent is not
-chased for a reply to it. For an announcement that needs no answer, either use
-`<swarm-broadcast>` or add `expects-reply="false"`.
-
-You may also send from your shell, which is useful mid-task rather than at the
-end of a turn (but you must then quote the text yourself):
-
-    swarm send --to AGENT_NAME "MESSAGE TEXT"
-    swarm broadcast "MESSAGE TEXT"
-
-### When the other agent is busy
-
-An agent already working on a task will refuse your message. That is normal. A
-tagged `<swarm-send>` is queued for them automatically. From the shell you choose:
-
-    swarm send --to AGENT_NAME --queue "MESSAGE TEXT"   # delivered when they are free
-    swarm send --to AGENT_NAME --wait  "MESSAGE TEXT"   # block until they are free
-    swarm queue AGENT_NAME                              # see what is waiting for them
-
-Prefer queueing, then get on with other work. Never spin in a retry loop.
-
-### Rules
-
-  * `AGENT_NAME`, `MESSAGE TEXT` and `m-1a2b3c` above are placeholders. Replace
-    them with a real agent from the list and what you actually want to say. A
-    `<swarm-send>` addressed to a name that is not an agent is discarded.
-  * Only message the agents listed above. Messaging anyone else will be refused.
-  * Keep messages self-contained -- the other agent does not see your screen,
-    your files, or your reasoning.
-  * Do not message an agent merely to acknowledge. Send when you have a question,
-    a result, or a handoff.
-  * Write a full tag block only when you actually want to send. A complete
-    `<swarm-send to="...">...</swarm-send>` you write is delivered, so do not paste
-    a filled-in example to illustrate a point -- it would be sent for real. Naming
-    the tag in passing while you explain your plan is fine.
-  * A turn with no tag simply sends nothing, which is normal and expected. The one
-    exception: if another agent asked YOU something and your turn ends with no
-    block, your answer reaches nobody, so you get a single reminder. Never add a
-    block just to satisfy the reminder -- only to actually answer.
-"""
-
-DEFAULT_REPLY_REMINDER_TEMPLATE = """\
-Your last turn sent no message to anyone, and {sender} is waiting on your answer
-to message {id}.
-
-{problems}
-
-Anything you write outside a message block stays on your own screen. The other
-agent cannot see your reasoning, your files, or your reply. To actually send it,
-put your answer inside a block exactly like this:
-
-<swarm-send to="{sender}" reply-to="{id}">
-your answer here, over as many lines as you need
-</swarm-send>
-
-Agents you may message: {peers}
-
-If you already wrote the answer, write it again inside that block. If you
-deliberately have nothing to send, ignore this -- you will not be reminded again.
-"""
-
-DEFAULT_SEND_FAILED_TEMPLATE = """\
-Your last turn tried to send a message, but it could not be delivered.
-
-{problems}
-
-Fix it and send again. The block must look exactly like this, closing tag included:
-
-<swarm-send to="AGENT_NAME">
-your message here
-</swarm-send>
-
-Agents you may message: {peers}
-
-You will not be reminded again.
-"""
-
-DEFAULT_TASK_NOTICE_TEMPLATE = """\
----
-## Standby
-
-Do not start any work yet. Your actual task will be sent to you in the **next**
-prompt. For now, reply with one plain sentence confirming you understood your role
--- no message block and no tags, this confirmation is just for your own screen and
-is not sent to anyone -- then wait.
-"""
-
 
 @dataclass
 class Agent:
@@ -205,19 +100,34 @@ class Agent:
     session: str
     capture: str
     boot_delay_ms: int
-    first_prompt: str
-    can_talk_to: list[str] = field(default_factory=list)
-    forward_responses_to: list[str] = field(default_factory=list)
+    role: str
+    can_talk_to: list[str]
+    mail_dir: Path
+    periodically_ping_seconds: int = 0
+    periodically_ping_message: str = ""
+    resume_args: str | None = None
+    resume_command: str | None = None
     env: dict[str, str] = field(default_factory=dict)
-    append_peers_prompt: bool = True
-    append_task_notice: bool = False
-    ready_probe: bool = True
     create_workdir: bool = True
+    ready_probe: bool = True
     busy_check: bool = True
-    parse_outbound_tags: bool = True
-    reply_reminder: bool = True
-    resume_args: str | None = None
-    resume_command: str | None = None
+
+
+@dataclass
+class TelegramConfig:
+    """Optional Telegram bridge settings (parsed from a top-level ``telegram:``).
+
+    Off by default. ``mirror`` is ``"*"`` (mirror every agent's mail) or a list of
+    agent names. Mail addressed to ``user`` is mirrored per ``mirror_user`` so the
+    human stays reachable even while "away"; ``system`` noise is off by default.
+    """
+
+    enabled: bool = False
+    bot_token: str = ""
+    chat_id: str = ""
+    mirror: Any = "*"
+    mirror_user: bool = True
+    mirror_system: bool = False
 
 
 @dataclass
@@ -227,45 +137,57 @@ class SwarmConfig:
     root: Path
     session_prefix: str
     agents: list[Agent]
+    # Paste-timing knobs consumed by lib/tmux.py (keep in sync with that module).
     enter_delay_ms: int = 250
     send_delay_ms: int = 150
-    max_forward_hops: int = 3
+    supervise: bool = True
+    supervise_interval_ms: int = 15000
     ready_timeout_ms: int = 60000
     busy_timeout_ms: int = 900000
-    message_format: str = "tagged"
-    max_reply_reminders: int = 1
-    resume: bool = False
-    reply_reminder_template: str = DEFAULT_REPLY_REMINDER_TEMPLATE
-    send_failed_template: str = DEFAULT_SEND_FAILED_TEMPLATE
+    # Resume is ON by default: `up` reattaches each agent to the conversation
+    # recorded in .agentainer/sessions.yaml. Opt out with `swarm.resume: false`
+    # in the config, or `agentainer up --no-resume`, or `agentainer remove-session`.
+    resume: bool = True
+    user_available: bool = False
     pane_idle_ms: int = 2500
     pane_poll_ms: int = 700
     pane_scrollback: int = 400
     tmux_history_limit: int = 50000
     tmux_mouse: bool = True
-    supervise: bool = True
-    supervise_interval_ms: int = 15000
+    telegram: "TelegramConfig" = field(default_factory=TelegramConfig)
     warnings: list[str] = field(default_factory=list)
 
+    def __post_init__(self) -> None:
+        # Set of resolved mail_dirs shared by 2+ agents. Computed up front so
+        # `mail_paths` can namespace mailbox folders to avoid collisions. Keyed on
+        # mail_dir (where the four folders actually live), NOT workdir: two agents
+        # can point a shared `mail_dir` at one place while keeping distinct
+        # workdirs, and without this they would silently share one `inbox/`.
+        counts: dict[Path, int] = {}
+        for agent in self.agents:
+            key = agent.mail_dir.resolve()
+            counts[key] = counts.get(key, 0) + 1
+        self._shared: set[Path] = {d for d, n in counts.items() if n > 1}
+
     @property
     def runtime(self) -> Path:
-        return self.root / ".swarm"
+        """Orchestrator-private state (logs, queue, run, sessions)."""
+        return self.root / ".agentainer"
 
     @property
     def log_dir(self) -> Path:
         return self.runtime / "logs"
 
     @property
-    def inbox_dir(self) -> Path:
-        return self.runtime / "inbox"
+    def queue_dir(self) -> Path:
+        # Per-agent pending-message buffer (one-at-a-time release lives here).
+        # Not created by the config layer -- just the authoritative path.
+        return self.runtime / "queue"
 
     @property
     def run_dir(self) -> Path:
         return self.runtime / "run"
 
-    @property
-    def bin_dir(self) -> Path:
-        return self.runtime / "bin"
-
     @property
     def sessions_file(self) -> Path:
         """Where each agent's conversation id is recorded, so `up --resume` works."""
@@ -281,6 +203,25 @@ class SwarmConfig:
     def names(self) -> list[str]:
         return [a.name for a in self.agents]
 
+    def mail_paths(self, agent: Agent) -> SimpleNamespace:
+        """Resolve the five mailbox folders for *agent* (plan §16).
+
+        Base is ``agent.mail_dir``. When that mail_dir is shared by more than one
+        agent (whether because they share a workdir and inherit the default, or
+        because they explicitly point at the same directory), every folder is
+        prefixed with ``<name>-`` to avoid collisions. The model never sees this
+        -- every nudge/first-prompt is handed the exact computed paths.
+        """
+        base = agent.mail_dir
+        prefix = agent.name + "-" if agent.mail_dir.resolve() in self._shared else ""
+        return SimpleNamespace(
+            inbox=base / (prefix + "inbox"),
+            outbox=base / (prefix + "outbox"),
+            read=base / (prefix + "read"),
+            sent=base / (prefix + "sent"),
+            failed=base / (prefix + "failed"),
+        )
+
 
 def _as_list(value: Any, ctx: str) -> list[str]:
     if value is None:
@@ -308,13 +249,56 @@ def _as_str_map(value: Any, ctx: str) -> dict[str, str]:
     return {str(k): str(v) for k, v in value.items()}
 
 
+def _parse_mirror(value: Any) -> Any:
+    """Normalise ``telegram.mirror``: ``*``/``all``/None -> ``"*"``; else a list."""
+    if value is None:
+        return "*"
+    if isinstance(value, str):
+        return "*" if value.strip().lower() in ("*", "all") else [value]
+    if isinstance(value, list):
+        return [str(v) for v in value]
+    raise ConfigError("telegram.mirror: expected '*', 'all', or a list of agent names")
+
+
+def _load_telegram(data: dict) -> "TelegramConfig":
+    raw = data.get("telegram") or {}
+    if not isinstance(raw, dict):
+        raise ConfigError("`telegram:` must be a mapping")
+    return TelegramConfig(
+        enabled=_as_bool(raw.get("enabled"), False, "telegram.enabled"),
+        bot_token=str(raw.get("bot_token") or ""),
+        chat_id=str(raw.get("chat_id") or ""),
+        mirror=_parse_mirror(raw.get("mirror")),
+        mirror_user=_as_bool(raw.get("mirror_user"), True, "telegram.mirror_user"),
+        mirror_system=_as_bool(raw.get("mirror_system"), False, "telegram.mirror_system"),
+    )
+
+
+def _expand_path(raw: Any, ctx: str, name: str, root: Path, swarm_name: str,
+                 atype: str, cfg_parent: Path) -> Path:
+    """Expand an optional {name}/{root}/{swarm}/{type} placeholder and resolve
+    the result relative to the config file's parent directory."""
+    text = str(raw)
+    try:
+        expanded = text.format(name=name, root=str(root), swarm=swarm_name, type=atype)
+    except (KeyError, IndexError) as exc:
+        raise ConfigError(
+            f"{ctx}: unknown placeholder in {raw!r}: {exc}. "
+            "Available: {name} {root} {swarm} {type}"
+        ) from exc
+    path = Path(os.path.expanduser(expanded))
+    if not path.is_absolute():
+        path = (cfg_parent / path).resolve()
+    return path
+
+
 def load(path: str | os.PathLike) -> SwarmConfig:
     cfg_path = Path(path).expanduser().resolve()
     if not cfg_path.is_file():
         raise ConfigError(
             f"config file not found: {cfg_path}\n"
-            "   Create one with:  cp agents.example.yaml agents.yaml\n"
-            "   Or point at it:   agentainer -c /path/to/swarm.yaml up"
+            "   Create one with:  cp agentainer.example.yaml agentainer.yaml\n"
+            "   Or point at it:   agentainer -c /path/to/agentainer.yaml up"
         )
 
     try:
@@ -333,12 +317,6 @@ def load(path: str | os.PathLike) -> SwarmConfig:
     if not isinstance(defaults, dict):
         raise ConfigError("`defaults:` must be a mapping")
 
-    templates = data.get("templates") or {}
-    comms_tpl = templates.get("comms") or DEFAULT_COMMS_TEMPLATE
-    notice_tpl = templates.get("task_notice") or DEFAULT_TASK_NOTICE_TEMPLATE
-    reminder_tpl = templates.get("reply_reminder") or DEFAULT_REPLY_REMINDER_TEMPLATE
-    failed_tpl = templates.get("send_failed") or DEFAULT_SEND_FAILED_TEMPLATE
-
     # Agent type registry: built-ins, overridable and extensible from YAML.
     types: dict[str, dict[str, Any]] = {
         k: dict(v) for k, v in BUILTIN_AGENT_TYPES.items()
@@ -357,23 +335,23 @@ def load(path: str | os.PathLike) -> SwarmConfig:
     swarm_name = str(swarm.get("name") or cfg_path.stem)
     create_workdirs = _as_bool(swarm.get("create_workdirs"), True, "swarm.create_workdirs")
 
-    message_format = str(swarm.get("message_format") or "tagged")
-    if message_format not in VALID_MESSAGE_FORMATS:
-        raise ConfigError(
-            f"swarm.message_format must be one of {', '.join(VALID_MESSAGE_FORMATS)}"
-        )
-
     raw_agents = data.get("agents")
-    if not raw_agents:
-        raise ConfigError("`agents:` must contain at least one agent")
+    if raw_agents is None:
+        # An empty swarm is valid: `agentainer up` brings up just the orchestrator
+        # + UI, and the operator seeds agents from a template / the Settings editor
+        # (P4). This also lets the UI remove the last agent without wedging.
+        raw_agents = []
     if not isinstance(raw_agents, list):
         raise ConfigError("`agents:` must be a list")
 
+    # Default mailbox base, if any (overridable per agent).
+    default_mail_dir_raw = defaults.get("mail_dir")
+
     # Pass 1: materialise agents without resolving peer references.
     agents: list[Agent] = []
     seen: set[str] = set()
-    # Warnings collected while resolving each agent (e.g. capture upgrades).
-    capture_warnings: list[str] = []
+    # Warnings collected while resolving each agent (capture upgrades + deprecations).
+    agent_warnings: list[str] = []
     for index, raw in enumerate(raw_agents):
         if not isinstance(raw, dict):
             raise ConfigError(f"agents[{index}]: must be a mapping")
@@ -385,6 +363,11 @@ def load(path: str | os.PathLike) -> SwarmConfig:
                 f"agent {name!r}: name must match {NAME_RE.pattern} "
                 "(it is used as a tmux session name and a directory name)"
             )
+        if name in ("user", "system"):
+            raise ConfigError(
+                f"agent {name!r}: user and system are reserved virtual mailboxes "
+                "and cannot be agent names"
+            )
         if name in seen:
             raise ConfigError(f"duplicate agent name: {name!r}")
         seen.add(name)
@@ -402,9 +385,23 @@ def load(path: str | os.PathLike) -> SwarmConfig:
         if not command:
             raise ConfigError(f"agent {name!r}: no `command` and type {atype!r} has none")
 
-        capture = str(
-            raw.get("capture") or defaults.get("capture") or "auto"
-        )
+        # type <-> command mismatch: a command that launches a DIFFERENT agent
+        # CLI than `type` implies will never fire its turn-completion signal and
+        # pins the agent "busy" forever. Lenient for key-free mocks (word-boundaries).
+        if atype in CLI_TOKENS:
+            cmd_lower = str(command).lower()
+            for token in CLI_TOKENS:
+                if token == atype:
+                    continue
+                if re.search(r"\b" + re.escape(token) + r"\b", cmd_lower):
+                    raise ConfigError(
+                        f"agent {name!r}: type: {atype} but command launches "
+                        f"{token!r} ({command!r}). The command must launch the same "
+                        f"agent CLI as `type`, or the turn-completion signal will "
+                        f"never fire and the agent will hang. Fix `command` or `type`."
+                    )
+
+        capture = str(raw.get("capture") or defaults.get("capture") or "auto")
         if capture not in VALID_CAPTURE:
             raise ConfigError(
                 f"agent {name!r}: capture must be one of {', '.join(VALID_CAPTURE)}"
@@ -414,15 +411,13 @@ def load(path: str | os.PathLike) -> SwarmConfig:
         # capture: none on a type that HAS a completion hook (claude/codex) removes
         # the agent's only turn-completion signal and leaves the orchestrator blind
         # to a silent turn -- which can wedge the whole swarm. Auto-upgrade to the
-        # type's natural capture so the hook keeps the orchestrator informed (and
-        # re-enables busy_check / tag parsing / reply reminders, force-disabled for
-        # capture: none below). gemini/hermes deliberately keep capture: none.
+        # type's natural capture so the hook keeps the orchestrator informed.
         if capture == "none" and str(tconf.get("capture")) == "hook":
             capture = "hook"
-            capture_warnings.append(
+            agent_warnings.append(
                 f"agent {name!r}: capture: none on a {atype} agent gives the "
                 f"orchestrator no turn-completion signal -- auto-upgraded to "
-                f"capture: hook. Use capture: pane (gemini/hermes) for deliberate-send."
+                f"capture: hook."
             )
 
         boot = raw.get("boot_delay_ms")
@@ -431,38 +426,51 @@ def load(path: str | os.PathLike) -> SwarmConfig:
         if boot is None:
             boot = tconf.get("boot_delay_ms", 5000)
 
-        first_prompt = raw.get("first_prompt")
+        # Standing instructions. `role` is the v2 field; `first_prompt` is a
+        # deprecated alias (warn). `first_prompt_file` is likewise deprecated.
+        role = raw.get("role")
         prompt_file = raw.get("first_prompt_file")
+        if prompt_file and (role is not None or raw.get("first_prompt") is not None):
+            raise ConfigError(
+                f"agent {name!r}: set either `role`/`first_prompt` or "
+                "`first_prompt_file`, not both"
+            )
         if prompt_file:
-            if first_prompt:
-                raise ConfigError(
-                    f"agent {name!r}: set either `first_prompt` or `first_prompt_file`, not both"
-                )
             fp = Path(os.path.expanduser(str(prompt_file)))
             if not fp.is_absolute():
                 fp = cfg_path.parent / fp
             if not fp.is_file():
                 raise ConfigError(f"agent {name!r}: first_prompt_file not found: {fp}")
-            first_prompt = fp.read_text()
-        first_prompt = (first_prompt or "").strip()
+            role = fp.read_text()
+        if "first_prompt" in raw:
+            agent_warnings.append(
+                f"agent {name!r}: `first_prompt` is deprecated; use `role`"
+            )
+        if "first_prompt_file" in raw:
+            agent_warnings.append(
+                f"agent {name!r}: `first_prompt_file` is deprecated; use `role` "
+                "(write the text directly, or read the file yourself)"
+            )
+        role = (role or raw.get("first_prompt") or "").strip()
 
         workdir_raw = raw.get("workdir") or defaults.get("workdir")
-        if workdir_raw:
-            # {name}, {root} and {swarm} let one `defaults.workdir` serve every agent.
-            try:
-                expanded = str(workdir_raw).format(
-                    name=name, root=str(root), swarm=swarm_name, type=atype
-                )
-            except (KeyError, IndexError) as exc:
-                raise ConfigError(
-                    f"agent {name!r}: unknown placeholder in workdir {workdir_raw!r}: {exc}. "
-                    "Available: {name} {root} {swarm} {type}"
-                ) from exc
-            workdir = Path(os.path.expanduser(expanded))
-            if not workdir.is_absolute():
-                workdir = (cfg_path.parent / workdir).resolve()
-        else:
-            workdir = root / name
+        workdir = (
+            _expand_path(workdir_raw, f"agent {name}: workdir", name, root,
+                         swarm_name, atype, cfg_path.parent)
+            if workdir_raw
+            else root / name
+        )
+
+        # Mailbox base: per-agent mail_dir overrides the global default, both
+        # resolved relative to the config file's parent. Default = the workdir,
+        # so by default the four folders live inside the workspace.
+        mail_dir_raw = raw.get("mail_dir") or default_mail_dir_raw
+        mail_dir = (
+            _expand_path(mail_dir_raw, f"agent {name}: mail_dir", name, root,
+                         swarm_name, atype, cfg_path.parent)
+            if mail_dir_raw
+            else workdir
+        )
 
         create_workdir = _as_bool(
             raw.get("create_workdir", defaults.get("create_workdir", create_workdirs)),
@@ -470,6 +478,16 @@ def load(path: str | os.PathLike) -> SwarmConfig:
             f"agent {name}: create_workdir",
         )
 
+        ping_seconds = raw.get("periodically_ping_seconds")
+        if ping_seconds is None:
+            ping_seconds = defaults.get("periodically_ping_seconds")
+        ping_seconds = int(ping_seconds or 0)
+        ping_message = (
+            raw.get("periodically_ping_message")
+            or defaults.get("periodically_ping_message")
+            or ""
+        )
+
         env = dict(_as_str_map(defaults.get("env"), "defaults.env"))
         env.update(_as_str_map(tconf.get("env"), f"agent_types.{atype}.env"))
         env.update(_as_str_map(raw.get("env"), f"agent {name}: env"))
@@ -483,109 +501,75 @@ def load(path: str | os.PathLike) -> SwarmConfig:
                 session=f"{prefix}{name}",
                 capture=capture,
                 boot_delay_ms=int(boot),
-                first_prompt=first_prompt,
+                role=role,
                 can_talk_to=_as_list(
                     raw.get("can_talk_to", defaults.get("can_talk_to")),
                     f"agent {name}: can_talk_to",
                 ),
-                forward_responses_to=_as_list(
-                    raw.get("forward_responses_to", defaults.get("forward_responses_to")),
-                    f"agent {name}: forward_responses_to",
-                ),
+                mail_dir=mail_dir,
+                periodically_ping_seconds=ping_seconds,
+                periodically_ping_message=str(ping_message),
+                resume_args=raw.get("resume_args")
+                or defaults.get("resume_args")
+                or tconf.get("resume_args"),
+                resume_command=raw.get("resume_command")
+                or defaults.get("resume_command")
+                or tconf.get("resume_command"),
                 env=env,
                 create_workdir=create_workdir,
                 # Busy tracking needs a "turn finished" signal, which only exists
                 # when the agent is captured. capture: none => always accept mail.
-                busy_check=_as_bool(
-                    raw.get("busy_check", defaults.get("busy_check")),
-                    True,
-                    f"agent {name}: busy_check",
-                )
-                and capture != "none",
-                # Routing <swarm-send> blocks means reading what the agent said,
-                # which is exactly what capture provides.
-                parse_outbound_tags=_as_bool(
-                    raw.get("parse_outbound_tags", defaults.get("parse_outbound_tags")),
-                    True,
-                    f"agent {name}: parse_outbound_tags",
-                )
-                and capture != "none"
-                and message_format == "tagged",
-                # Reminding an agent to use the tags only makes sense if we read
-                # them back and can see that it did not.
-                reply_reminder=_as_bool(
-                    raw.get("reply_reminder", defaults.get("reply_reminder")),
-                    True,
-                    f"agent {name}: reply_reminder",
-                ),
-                resume_args=raw.get("resume_args") or defaults.get("resume_args") or tconf.get("resume_args"),
-                resume_command=raw.get("resume_command") or defaults.get("resume_command") or tconf.get("resume_command"),
                 ready_probe=_as_bool(
                     raw.get("ready_probe", defaults.get("ready_probe")),
                     True,
                     f"agent {name}: ready_probe",
                 ),
-                append_peers_prompt=_as_bool(
-                    raw.get(
-                        "append_agents_that_you_can_talk_to_prompt",
-                        defaults.get("append_agents_that_you_can_talk_to_prompt"),
-                    ),
+                busy_check=_as_bool(
+                    raw.get("busy_check", defaults.get("busy_check")),
                     True,
-                    f"agent {name}: append_agents_that_you_can_talk_to_prompt",
-                ),
-                append_task_notice=_as_bool(
-                    raw.get(
-                        "in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt",
-                        defaults.get(
-                            "in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt"
-                        ),
-                    ),
-                    False,
-                    f"agent {name}: in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt",
-                ),
+                    f"agent {name}: busy_check",
+                )
+                and capture != "none",
             )
         )
 
     all_names = [a.name for a in agents]
 
-    # Pass 2: expand wildcards and validate the communication graph.
+    # Pass 2: expand wildcards and validate the communication graph. `user` is a
+    # permitted virtual recipient; `system` is orchestrator-only and may never be
+    # addressed by an agent; everything else must name a real agent.
     for agent in agents:
         if "*" in agent.can_talk_to:
-            agent.can_talk_to = [n for n in all_names if n != agent.name]
+            # `*` means "every other agent". Preserve any other entries listed
+            # alongside it (notably `user`, which `*` does not cover) instead of
+            # replacing the whole list -- dropping an explicit recipient would
+            # deny mail the config plainly granted.
+            expanded = [n for n in all_names if n != agent.name]
+            extras = [
+                p
+                for p in agent.can_talk_to
+                if p != "*" and p != agent.name and p not in expanded
+            ]
+            agent.can_talk_to = expanded + extras
         for peer in agent.can_talk_to:
-            if peer not in all_names:
+            if peer == "system":
                 raise ConfigError(
-                    f"agent {agent.name!r}: can_talk_to references unknown agent {peer!r}"
+                    f"agent {agent.name!r}: `system` is a reserved orchestrator "
+                    "mailbox and can never be a recipient -- remove it from "
+                    "can_talk_to"
                 )
-            if peer == agent.name:
-                raise ConfigError(f"agent {agent.name!r}: cannot be in its own can_talk_to")
-
-        if "*" in agent.forward_responses_to:
-            agent.forward_responses_to = list(agent.can_talk_to)
-        for peer in agent.forward_responses_to:
+            if peer == "user":
+                continue
             if peer not in all_names:
                 raise ConfigError(
-                    f"agent {agent.name!r}: forward_responses_to references unknown agent {peer!r}"
+                    f"agent {agent.name!r}: can_talk_to references unknown agent "
+                    f"{peer!r}"
                 )
-            if peer not in agent.can_talk_to:
-                raise ConfigError(
-                    f"agent {agent.name!r}: forward_responses_to includes {peer!r}, "
-                    "which is not in its can_talk_to list"
-                )
-        if agent.forward_responses_to and agent.capture == "none":
-            raise ConfigError(
-                f"agent {agent.name!r}: forward_responses_to needs capture to be enabled "
-                "(set capture: hook or capture: pane)"
-            )
+            if peer == agent.name:
+                raise ConfigError(f"agent {agent.name!r}: cannot be in its own can_talk_to")
 
-    # Pass 2b: working directories. They may be auto-created under `root`, or
-    # point at an existing project -- possibly one shared by several agents.
     warnings: list[str] = []
-    warnings.extend(capture_warnings)
-    for agent in agents:
-        # No tag parsing means no way to know whether it replied.
-        if not agent.parse_outbound_tags:
-            agent.reply_reminder = False
+    warnings.extend(agent_warnings)
 
     for agent in agents:
         if agent.workdir.exists() and not agent.workdir.is_dir():
@@ -618,14 +602,12 @@ def load(path: str | os.PathLike) -> SwarmConfig:
         agents=agents,
         enter_delay_ms=int(swarm.get("enter_delay_ms", 250)),
         send_delay_ms=int(swarm.get("send_delay_ms", 150)),
-        max_forward_hops=int(swarm.get("max_forward_hops", 3)),
         ready_timeout_ms=int(swarm.get("ready_timeout_ms", 60000)),
         busy_timeout_ms=int(swarm.get("busy_timeout_ms", 900000)),
-        message_format=message_format,
-        max_reply_reminders=int(swarm.get("max_reply_reminders", 1)),
-        resume=_as_bool(swarm.get("resume"), False, "swarm.resume"),
-        reply_reminder_template=reminder_tpl,
-        send_failed_template=failed_tpl,
+        resume=_as_bool(swarm.get("resume"), True, "swarm.resume"),
+        user_available=_as_bool(
+            swarm.get("user_available"), False, "swarm.user_available"
+        ),
         pane_idle_ms=int(swarm.get("pane_idle_ms", 2500)),
         pane_poll_ms=int(swarm.get("pane_poll_ms", 700)),
         pane_scrollback=int(swarm.get("pane_scrollback", 400)),
@@ -633,29 +615,6 @@ def load(path: str | os.PathLike) -> SwarmConfig:
         tmux_mouse=_as_bool(swarm.get("tmux_mouse"), True, "swarm.tmux_mouse"),
         supervise=_as_bool(swarm.get("supervise"), True, "swarm.supervise"),
         supervise_interval_ms=int(swarm.get("supervise_interval_ms", 15000)),
+        telegram=_load_telegram(data),
     )
-
-    # Pass 3: build the full first prompt for each agent.
-    for agent in agents:
-        cfg_get = {
-            "agent": agent.name,
-            "swarm": cfg.name,
-            "prefix": cfg.session_prefix,
-            "peers": ", ".join(agent.can_talk_to) or "none (you are isolated)",
-            "inbox": str(cfg.inbox_dir / agent.name),
-            "workdir": str(agent.workdir),
-        }
-        parts = [agent.first_prompt] if agent.first_prompt else []
-        try:
-            if agent.append_peers_prompt:
-                parts.append(comms_tpl.format(**cfg_get).strip())
-            if agent.append_task_notice:
-                parts.append(notice_tpl.format(**cfg_get).strip())
-        except (KeyError, IndexError, ValueError) as exc:
-            raise ConfigError(
-                f"agent {agent.name!r}: a template placeholder is not recognised: {exc}. "
-                f"Available: {', '.join(sorted(cfg_get))}"
-            ) from exc
-        agent.first_prompt = "\n\n".join(p.strip() for p in parts if p.strip())
-
     return cfg