agentainer 2.0.0 → 2.0.1

package/examples/white-paper-research.yaml

@@ -0,0 +1,96 @@
+# =============================================================================
+# 📄 White-paper research -- a hub researcher gathers B2B source material, then
+# an analyst synthesizes it, a writer drafts the paper, and a design brief is
+# produced for layout. Turns a fuzzy topic into a publishable white-paper package.
+#
+#   cp examples/white-paper-research.yaml my-paper.yaml
+#   agentainer up    -c my-paper.yaml
+#   agentainer send  -c my-paper.yaml --to topic_researcher "White paper on zero-trust security for mid-market SaaS."
+#   agentainer down  -c my-paper.yaml
+#
+# The communication graph is a hub-and-spoke: the researcher is the only agent
+# that talks to the human and the only one that reaches the three specialists,
+# so raw sources are gathered once and fanned out to synthesis, drafting and
+# design instead of each specialist re-researching the topic.
+#
+#   user <──> topic_researcher   (the hub)
+#                  /   |   \
+#                 /    |    \
+#          analyst  draft_writer  design_brief_writer
+#   ...the three specialists never talk to each other; everything flows
+#   through the researcher, who owns the topic and the source material.
+#
+# Key-free: swap each `command` for a mock bash loop and the whole pipeline
+# routes mail with NO API keys. The `command` lines below launch the real CLIs.
+# =============================================================================
+
+swarm:
+  name: white-paper-research
+  root: ./white-paper-research-workspace
+
+defaults:
+  capture: none              # tightened per agent below
+  can_talk_to: []            # default ACL is "talk to no one"; set per agent
+
+agents:
+  - name: topic_researcher
+    type: claude
+    can_talk_to: [analyst, draft_writer, design_brief_writer, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the TOPIC RESEARCHER and hub for a white-paper project. You take a
+      B2B topic from the user, scope the angle and audience, and gather the raw
+      source material: market data, competitive landscape, standards, customer
+      pain points, and credible citations. You do NOT write the paper -- you own
+      the facts and the brief.
+      Run it like this: (1) restate the topic as a one-paragraph scope + the
+      target reader + 3-5 key questions the paper must answer; (2) collect and
+      organize sources and findings into a research pack; (3) send the pack to
+      the analyst for synthesis; (4) once the analyst returns a thesis and
+      outline, brief the draft_writer to write and the design_brief_writer to
+      spec the layout; (5) return the finished package to the user.
+      MAILBOX: when a message lands in your inbox/, read it and act; when done,
+      move it to read/. To send, write a file into outbox/<name>/ (read
+      outbox/<name>/about.md first) and finish your turn. You may message the
+      agents in your can_talk_to.
+
+  - name: analyst
+    type: claude
+    can_talk_to: [topic_researcher]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the ANALYST. Given the researcher's source pack, turn raw findings
+      into a defensible argument: identify the central thesis, the 3-5 supporting
+      points, the counter-arguments to pre-empt, and a section-by-section outline
+      for the white paper. Separate what the sources prove from what is
+      inference; flag any claim that needs a stronger citation. Write your
+      synthesis and outline, then report back to the topic_researcher. If the
+      source pack is thin or contradictory, say so and ask for more -- do not
+      paper over gaps.
+
+  - name: draft_writer
+    type: codex
+    can_talk_to: [topic_researcher]
+    command: "codex --yolo"
+    role: |
+      You are the DRAFT WRITER. Given the analyst's thesis and outline (relayed
+      by the researcher) plus the source pack, write the white-paper draft:
+      executive summary, body sections following the outline, and a conclusion
+      with a clear call to action. Write for a B2B decision-maker -- authoritative,
+      concrete, jargon-checked -- and cite sources inline as the analyst mapped
+      them. Do not invent statistics; if a section lacks support, ask the
+      researcher rather than filling the gap. Send the completed draft back to
+      the topic_researcher.
+
+  - name: design_brief_writer
+    type: claude
+    can_talk_to: [topic_researcher]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the DESIGN BRIEF WRITER. Given the outline and draft (relayed by
+      the researcher), produce a design brief a layout designer can execute:
+      recommended page count and structure, where pull-quotes and callouts go,
+      which data points become charts or infographics (and the chart type),
+      cover concept, and a tone/visual-style note aligned to the target reader.
+      You specify the visual plan; you do not design pixels. Send the brief back
+      to the topic_researcher.

package/examples/youtube-script-studio.yaml

@@ -0,0 +1,107 @@
+# =============================================================================
+# 🎬 YouTube script studio -- turn a video topic into a full publish-ready
+# package: script -> title/thumbnail copy -> description + tags + chapters.
+#
+#   cp examples/youtube-script-studio.yaml my-studio.yaml
+#   agentainer up   -c my-studio.yaml
+#   agentainer send -c my-studio.yaml --to producer "Make a 10-min video: 'Why your sourdough won't rise'."
+#   agentainer down -c my-studio.yaml
+#
+# The producer is the hub: it briefs a researcher (hooks + retention patterns),
+# a scriptwriter (the actual script), and a metadata_writer (title, thumbnail
+# copy, description, tags, chapters). Script and metadata are written as peers so
+# titles/chapters track the real script -- but the producer stays the only agent
+# that talks to you.
+#
+#        make a video X
+#   user ─────────────▶ producer ◀───────────────────────┐
+#        (package)  ◀──────┼──────────────┬───────────┐   │
+#                          ▼              ▼           ▼    │
+#                     researcher     scriptwriter  metadata_writer
+#                                          └────peer────┘
+#   ...producer <--> everyone; scriptwriter <--> metadata_writer; user via hub only.
+#
+# Key-free / no API keys: every `command` below is a placeholder launch line for a
+# real coding-agent CLI. Swap each for a mock bash loop and the whole studio comes
+# up and routes mail with NO API keys -- the mechanics are identical.
+# =============================================================================
+
+swarm:
+  name: youtube-script-studio
+  root: ./youtube-script-studio-workspace
+
+defaults:
+  capture: none              # tightened per agent (pane for gemini/hermes)
+  can_talk_to: []            # tightened per agent below
+
+agents:
+  - name: producer
+    type: claude
+    workdir: "{root}/repo"
+    can_talk_to: [researcher, scriptwriter, metadata_writer, user]
+    command: "claude --dangerously-skip-permissions"
+    capture: none
+    role: |
+      You are the PRODUCER, the hub of a YouTube video studio. You turn the
+      user's topic into a publish-ready package and are the ONLY agent who talks
+      to the user. You do not write the script yourself; you set the angle,
+      audience, target length, and the promise of the video, then coordinate.
+      Your team: researcher (hook ideas + retention/pacing patterns for this
+      topic), scriptwriter (writes the full script), metadata_writer (title
+      options, thumbnail copy, description, tags, chapter markers).
+      Run it like this: (1) restate the topic as a one-paragraph brief -- angle,
+      audience, length, the single promise -- and send it to the researcher
+      first; (2) pass the research to the scriptwriter to draft the script;
+      (3) have the metadata_writer build titles/thumbnail/description/tags/
+      chapters against the FINAL script; (4) assemble everything and send the
+      finished package to the user.
+      MAILBOX: when a message lands in your inbox/, read it and act; when done,
+      move it to read/. To send, write a file into outbox/<name>/ (read
+      outbox/<name>/about.md first to see who they are and whether they are
+      available) and finish your turn. You may only message the agents in your
+      can_talk_to list.
+
+  - name: researcher
+    type: gemini
+    workdir: "{root}/repo"
+    can_talk_to: [producer]
+    command: "gemini --yolo"
+    capture: pane
+    role: |
+      You are the RESEARCHER. Given the producer's brief, find what makes THIS
+      topic watchable: 3-5 strong hook openers, the questions the audience
+      actually types, the moments where viewers drop off and how to hold them
+      (pattern interrupts, open loops, payoff placement), and any facts or
+      angles worth including. You do not write the script -- you hand the
+      producer a tight research brief they can pass to the scriptwriter. Report
+      only to the producer.
+
+  - name: scriptwriter
+    type: claude
+    workdir: "{root}/repo"
+    can_talk_to: [producer, metadata_writer]
+    command: "claude --dangerously-skip-permissions"
+    capture: none
+    role: |
+      You are the SCRIPTWRITER. Given the producer's brief and the researcher's
+      findings, write the full video SCRIPT.md: a cold-open hook in the first 15
+      seconds, a clear through-line, spoken-word narration (not bullet points),
+      B-roll / on-screen cues in brackets, and a call to action. Match the
+      target length and audience. When the script is solid, send a copy straight
+      to the metadata_writer so titles and chapters track the real script, and
+      report the draft to the producer.
+
+  - name: metadata_writer
+    type: codex
+    workdir: "{root}/repo"
+    can_talk_to: [producer, scriptwriter]
+    command: "codex --yolo"
+    capture: none
+    role: |
+      You are the METADATA_WRITER. Working from the FINAL script, produce the
+      packaging that gets the video found and clicked: 5-8 title options (front-
+      load the keyword, keep them honest), thumbnail copy (2-4 punchy words),
+      an SEO description with the payoff in the first two lines, a tag list, and
+      timestamped chapter markers derived from the script's sections. If the
+      script is missing a section you need for a chapter, ask the scriptwriter
+      directly; deliver the finished packaging to the producer.

package/lib/cli.py

@@ -555,8 +555,7 @@ def cmd_queue(args) -> int:
                     dropped += 1
         info(f"{agent.name}: dropped {dropped} queued message(s)")
         return 0
-    q = cfg.queue_dir / agent.name
-    items = sorted(f for f in q.iterdir() if f.is_file()) if q.is_dir() else []
+    items = mail.queued_files(cfg, agent.name)
     state = turn.busy_info(cfg, agent)
     status = f"busy for {state['age_s']}s (task from {state['by']})" if state else "idle"
     print(f"{agent.name}: {status}, {len(items)} message(s) queued")
@@ -574,6 +573,11 @@ def cmd_idle(args) -> int:
     info(f"{agent.name}: marked idle")
     if not args.no_drain:
         mail.process_read_folder(cfg, agent.name)
+        # process_read_folder only archives an over-presented message; pair the
+        # release of the next queued message with a nudge, exactly as the
+        # supervisor tick does, so the escape hatch actually re-announces mail.
+        if mail.release_next(cfg, agent.name):
+            mail.nudge(cfg, agent.name)
     return 0
 
 

package/lib/config.py

@@ -158,11 +158,14 @@ class SwarmConfig:
     warnings: list[str] = field(default_factory=list)
 
     def __post_init__(self) -> None:
-        # Set of resolved workdirs shared by 2+ agents. Computed up front so
-        # `mail_paths` can namespace mailbox folders to avoid collisions.
+        # 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.workdir.resolve()
+            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}
 
@@ -203,13 +206,14 @@ class SwarmConfig:
     def mail_paths(self, agent: Agent) -> SimpleNamespace:
         """Resolve the five mailbox folders for *agent* (plan §16).
 
-        Base is ``agent.mail_dir``. When the agent's workdir is shared by more
-        than one agent, 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 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.workdir.resolve() in self._shared else ""
+        prefix = agent.name + "-" if agent.mail_dir.resolve() in self._shared else ""
         return SimpleNamespace(
             inbox=base / (prefix + "inbox"),
             outbox=base / (prefix + "outbox"),
@@ -332,8 +336,11 @@ def load(path: str | os.PathLike) -> SwarmConfig:
     create_workdirs = _as_bool(swarm.get("create_workdirs"), True, "swarm.create_workdirs")
 
     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")
 
@@ -533,7 +540,17 @@ def load(path: str | os.PathLike) -> SwarmConfig:
     # 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 == "system":
                 raise ConfigError(

package/lib/mail.py

@@ -29,6 +29,7 @@ Branding: "swarm" is retired -- it's Agentainer everywhere (decision D21).
 from __future__ import annotations
 
 import json
+import os
 import re
 import shutil
 import time
@@ -148,11 +149,23 @@ def enqueue(cfg: SwarmConfig, recipient: str, text: str, msg_id: str) -> None:
     After the message is durably queued, best-effort mirror it to Telegram (a
     no-op unless configured). Mirroring runs AFTER the write and can never raise
     -- correctness never depends on the network (see lib/telegram.py).
+
+    We stamp the queue file with a strictly-increasing modification time (>= every
+    file already queued for this recipient) so :func:`queued_files` gives true
+    FIFO. Filesystem mtime granularity can't be relied on: some filesystems hand
+    identical mtimes to writes made in the same coarse tick, which would let
+    release order fall back to the random message-id name and starve a message
+    whose id happens to sort late. Enqueues for one recipient are serialised by
+    this same lock, so max-existing+1 is a safe monotonic clock per queue.
     """
     with lock.file_lock(cfg, recipient, "mail"):
         q = cfg.queue_dir / recipient
         q.mkdir(parents=True, exist_ok=True)
-        (q / f"{msg_id}.txt").write_text(text)
+        path = q / f"{msg_id}.txt"
+        path.write_text(text)
+        prior = [f.stat().st_mtime_ns for f in q.iterdir() if f.is_file() and f != path]
+        stamp = max([time.time_ns()] + [p + 1 for p in prior])
+        os.utime(path, ns=(stamp, stamp))
     import telegram  # lazy: keeps mail's import graph free of the bridge
 
     telegram.on_enqueued(cfg, recipient, text, msg_id)
@@ -299,9 +312,35 @@ def standby_prompt(cfg: SwarmConfig, agent) -> str:
     )
 
 
+def _queue_order(path: Path):
+    """FIFO sort key for a queued message: enqueue time first, name as tie-break.
+
+    Message filenames are random ids (``m-<uuid8>.txt``), so sorting the queue
+    by *name* is a random order -- a message whose id happens to sort late gets
+    starved indefinitely as lower-sorting ids keep cutting in line. Queue files
+    are written once by ``enqueue`` and never modified, so ``st_mtime_ns`` is
+    the moment the message was enqueued: order by that to get true FIFO.
+    """
+    return (path.stat().st_mtime_ns, path.name)
+
+
+def queued_files(cfg: SwarmConfig, agent_name: str) -> list:
+    """Return *agent_name*'s queued message files in FIFO (enqueue-time) order.
+
+    A missing queue dir (agent never received mail) is treated as empty.
+    """
+    q = cfg.queue_dir / agent_name
+    if not q.exists():
+        return []
+    return sorted((f for f in q.iterdir() if f.is_file()), key=_queue_order)
+
+
 def release_next(cfg: SwarmConfig, agent_name: str) -> bool:
     """Release the oldest queued message into *agent_name*'s inbox (one-at-a-time).
 
+    "Oldest" is by enqueue time (see :func:`queued_files`), not filename -- the
+    ids are random, so filename order would starve a late-sorting message.
+
     Returns False if the inbox already holds a message (one-at-a-time) or the
     queue is empty; True if a message was moved into the inbox. Each release
     bumps the presentation counter used by the auto-archive fallback.
@@ -328,10 +367,7 @@ def release_next(cfg: SwarmConfig, agent_name: str) -> bool:
             # One-at-a-time: a message is already presented; count it as a presentation.
             _bump_presentations(cfg, agent_name, existing[0].name)
             return False
-        q = cfg.queue_dir / agent_name
-        # q may not exist yet for an agent that has never received mail;
-        # iterdir() would raise, so treat a missing queue as empty.
-        files = sorted(f for f in q.iterdir() if f.is_file()) if q.exists() else []
+        files = queued_files(cfg, agent_name)
         if not files:
             return False
         oldest = files[0]
@@ -373,13 +409,30 @@ def nudge(cfg: SwarmConfig, agent_name: str) -> bool:
         f"You can message: {allowed}."
     )
     try:
-        return tmux.paste_into(cfg, agent.session, nudge_text)
+        pasted = tmux.paste_into(cfg, agent.session, nudge_text)
     except tmux.SwarmError:
         # Best-effort: if the agent isn't up (or tmux is unavailable) the mail
         # still sits in the queue and gets released on the next sweep / when the
         # agent starts. Never crash a send because a session is missing -- a
         # paste failure just means we retry on the next tick.
         return False
+    if pasted:
+        # The agent was actually poked about a freshly delivered message, so it
+        # is now mid-turn. Mark the turn STARTED so busy-detection is accurate:
+        # otherwise (delivered stayed == completed after the first prompt) the
+        # supervisor treats a long but legitimate turn as idle, bumps the inbox
+        # message's presentation count every tick, and auto-archives it mid-turn
+        # -- yanking the task and corrupting the turn. The inbox holds exactly
+        # one message (one-at-a-time); its From is the task's origin.
+        sender = None
+        try:
+            msgs = sorted(f for f in mp.inbox.iterdir() if f.is_file())
+            if msgs:
+                sender = _parse_header_field(msgs[0].read_text(), "From")
+        except OSError:  # pragma: no cover - defensive only
+            sender = None
+        turn.mark_turn_started(cfg, agent_name, sender or "system")
+    return pasted
 
 
 def route_outbound(cfg: SwarmConfig, sender: str, recipient: str, body: str) -> str:
@@ -443,9 +496,10 @@ def on_stop(cfg: SwarmConfig, agent_name: str) -> dict:
                 if not sub.is_dir():
                     continue
                 recipient = sub.name
-                for f in sorted(sub.iterdir()):
-                    if not f.is_file():
-                        continue
+                # Route in the order the agent WROTE the files (enqueue/delivery
+                # order follows this), not by the model's arbitrary filenames --
+                # otherwise two messages to the same peer can arrive out of order.
+                for f in sorted((c for c in sub.iterdir() if c.is_file()), key=_queue_order):
                     # about.md is the orchestrator-maintained contact card, not
                     # an outbound message -- never route or delete it.
                     if f.name == "about.md":
@@ -513,21 +567,32 @@ def process_read_folder(cfg: SwarmConfig, agent_name: str) -> int:
     _save_run_json(cfg, f"{agent_name}.read.json", state)
 
     # Auto-archive fallback (plan §7): a single message presented >= N times
-    # without being handled is moved to the archive and the queue advances, so a
-    # forgetful model can never wedge the swarm.
+    # without being handled is moved to the archive so a forgetful model can
+    # never wedge the swarm. We only ARCHIVE here (empty the inbox); we do NOT
+    # release the next message, because the release must be paired with a nudge
+    # -- and every caller (supervisor tick, cmd_idle) runs release_next + nudge
+    # right after us. Releasing here (un-nudged) meant the freshly delivered
+    # message was never announced to the agent, so it silently climbed to its
+    # own auto-archive threshold and was discarded unread -- draining the whole
+    # queue into the archive. Leaving the inbox empty lets the caller's
+    # release+nudge deliver-and-announce the next message like any other.
     inbox = mp.inbox
     if inbox.exists():
         msgs = sorted(f for f in inbox.iterdir() if f.is_file())
         if len(msgs) == 1:
             f = msgs[0]
             pres = _get_presentations(cfg, agent_name)
+            # `processed` holds message CONTENT ids ("m-arc2"), so the
+            # "already handled" guard must compare the inbox message's own
+            # content id -- NOT f.name ("m-arc2.txt"), which never matches and
+            # would let a handled message be archived anyway.
+            inbox_id = _parse_header_field(f.read_text(), "Id")
             if (
                 pres.get("msg_id") == f.name
                 and pres.get("count", 0) >= AUTO_ARCHIVE_PRESENTATIONS
-                and f.name not in processed
+                and inbox_id not in processed
             ):
                 log.archive_message(cfg, agent_name, f)
-                release_next(cfg, agent_name)
 
     return count
 

package/lib/reconcile.py

@@ -157,6 +157,29 @@ def write_raw(path, data: dict) -> None:
 # --------------------------------------------------------------------------
 
 
+def _commit(cfg, raw: dict) -> "cfgmod.SwarmConfig":
+    """Persist *raw* to the config path, then validate by reloading it.
+
+    If the reload fails -- the edit produced an invalid config (e.g. a
+    can_talk_to reference to an agent that no longer exists) -- restore the
+    previous file and re-raise, so a REJECTED edit never leaves an unloadable
+    config on disk. Without this, every mutator wrote first and validated
+    second, and a rejected edit corrupted agentainer.yaml, breaking every later
+    command and the UI.
+    """
+    path = Path(cfg.path)
+    prev = path.read_text() if path.exists() else None
+    write_raw(path, raw)
+    try:
+        return cfgmod.load(path)
+    except Exception:
+        if prev is None:  # pragma: no cover - a mutator always starts from an existing config
+            path.unlink(missing_ok=True)
+        else:
+            path.write_text(prev)
+        raise
+
+
 def _coerce_field(key: str, value: str):
     """Turn a CLI string into the right Python value for *key*.
 
@@ -202,8 +225,7 @@ def add_agent(cfg, name, type_, command, can_talk_to, role="", workdir=None, **e
         entry[k] = v
     agents.append(entry)
     raw["agents"] = agents
-    write_raw(cfg.path, raw)
-    return cfgmod.load(cfg.path)
+    return _commit(cfg, raw)
 
 
 def remove_agent(cfg, name) -> "cfgmod.SwarmConfig":
@@ -217,9 +239,18 @@ def remove_agent(cfg, name) -> "cfgmod.SwarmConfig":
     kept = [a for a in agents if str(a.get("name")) != name]
     if len(kept) == len(agents):
         raise ValueError(f"agent {name!r} not found")
+    # Strip the removed agent from every remaining agent's can_talk_to. Config
+    # load validates that every peer exists (config.py), so a lingering
+    # reference would make the reload below raise -- after we've already written
+    # the file -- leaving an unloadable config on disk that breaks every later
+    # command and the UI. A "*" wildcard needs no cleanup: load re-expands it to
+    # whatever agents remain.
+    for a in kept:
+        talk = a.get("can_talk_to")
+        if isinstance(talk, list):
+            a["can_talk_to"] = [p for p in talk if str(p) != name]
     raw["agents"] = kept
-    write_raw(cfg.path, raw)
-    return cfgmod.load(cfg.path)
+    return _commit(cfg, raw)
 
 
 def edit_swarm(cfg, **fields) -> "cfgmod.SwarmConfig":
@@ -234,8 +265,7 @@ def edit_swarm(cfg, **fields) -> "cfgmod.SwarmConfig":
     for k, v in fields.items():
         swarm[k] = v
     raw["swarm"] = swarm
-    write_raw(cfg.path, raw)
-    return cfgmod.load(cfg.path)
+    return _commit(cfg, raw)
 
 
 def edit_telegram(cfg, **fields) -> "cfgmod.SwarmConfig":
@@ -249,8 +279,26 @@ def edit_telegram(cfg, **fields) -> "cfgmod.SwarmConfig":
     for k, v in fields.items():
         tg[k] = v
     raw["telegram"] = tg
+    return _commit(cfg, raw)
+
+
+def apply_template(cfg, agents, defaults=None) -> list:
+    """Seed an EMPTY config on disk with a template's ``agents`` (+ ``defaults``).
+
+    Onboarding helper: copies an example swarm's agent list into the current
+    ``agentainer.yaml`` when it has no agents yet, and pulls in the template's
+    ``defaults`` block if the target has none. Returns the added agent names.
+    Raises ``ValueError`` if the config already has agents (templates seed a
+    fresh swarm rather than merging into a live one).
+    """
+    raw = load_raw(cfg.path)
+    if raw.get("agents"):
+        raise ValueError("swarm already has agents")
+    if defaults and not raw.get("defaults"):
+        raw["defaults"] = dict(defaults)
+    raw["agents"] = list(agents)
     write_raw(cfg.path, raw)
-    return cfgmod.load(cfg.path)
+    return [str(a.get("name")) for a in agents if a.get("name")]
 
 
 def edit_agent(cfg, name, **fields) -> "cfgmod.SwarmConfig":
@@ -270,8 +318,7 @@ def edit_agent(cfg, name, **fields) -> "cfgmod.SwarmConfig":
             break
     if not found:
         raise ValueError(f"agent {name!r} not found")
-    write_raw(cfg.path, raw)
-    return cfgmod.load(cfg.path)
+    return _commit(cfg, raw)
 
 
 # --------------------------------------------------------------------------
@@ -399,6 +446,30 @@ def stop_one(cfg, name: str) -> bool:
     return True
 
 
+def start_all(cfg, *, _start_fn=None) -> list:
+    """Start every configured-but-not-running agent; return the started names.
+
+    A thin wrapper over ``reconcile`` (start-only) so the UI's "Start all" button
+    has one authoritative launch path. ``_start_fn`` is injectable for tests.
+    """
+    return reconcile(cfg, start_missing=True, stop_extra=False, _start_fn=_start_fn)["started"]
+
+
+def stop_all(cfg) -> list:
+    """Kill every running agent session (config untouched); return stopped names.
+
+    Mirrors ``stop_one`` across the whole swarm for the UI's "Stop all" button;
+    agents that are already down are skipped.
+    """
+    stopped: list[str] = []
+    for a in cfg.agents:
+        if tmux.session_exists(a.session):
+            tmux.tmux("kill-session", "-t", f"={a.session}", check=False, capture=True)
+            stopped.append(a.name)
+            info(f"stop_all: stopped {a.name}")
+    return stopped
+
+
 # --------------------------------------------------------------------------
 # CLI handlers
 # --------------------------------------------------------------------------

package/lib/turn.py

@@ -79,12 +79,20 @@ def busy_info(cfg: SwarmConfig, agent: Agent) -> dict | None:
 
 
 def mark_turn_started(cfg: SwarmConfig, agent: str, sender: str) -> None:
-    """Record that another message (from *sender*) was just delivered to *agent*."""
-    state = turn_state(cfg, agent)
-    state["delivered"] = state.get("delivered", 0) + 1
-    state["since"] = time.time()
-    state["by"] = sender
-    write_turn_state(cfg, agent, state)
+    """Record that another message (from *sender*) was just delivered to *agent*.
+
+    Locked with the same ``turn.lock`` as :func:`mark_turn_finished`: this is a
+    read-modify-write of ``delivered``, and the completion hook (a separate
+    process) clamps ``completed`` concurrently. Without the shared lock the two
+    can interleave and lose an update, leaving an agent wedged "busy" or -- worse
+    -- looking idle while a message is still in flight.
+    """
+    with file_lock(cfg, agent, "turn.lock"):
+        state = turn_state(cfg, agent)
+        state["delivered"] = state.get("delivered", 0) + 1
+        state["since"] = time.time()
+        state["by"] = sender
+        write_turn_state(cfg, agent, state)
 
 
 def mark_turn_finished(cfg: SwarmConfig, agent: str) -> None: