docs(svc-ai-agent-broker): record why swarm never creates an agent

ensure() puts the broker itself on the freshly created per-agent overlay before backend.create() runs, and a swarm service task cannot be attached to another network at runtime. The connect burns the full realize_timeout and the create is never reached, so the CLI test reads no such service and every relayed prompt answers 502. Compose is unaffected: its driver is bridge and attaching a running container works.

The agent side is already correct, attached declaratively through TaskTemplate.Networks, so only the broker's own attachment is impossible. Both exits cost something that is not a code detail: listing the broker's overlay in the agent's Networks removes the hot-attach but gives up network isolation between owners, and keeping the per-agent overlay means reaching the agent over a cluster-wide published port. Deferred by the operator, so the swarm path stays known-broken and its jobs stay red.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

roles/svc-ai-agent-broker/TODO.md

@@ -0,0 +1,3 @@
+# TODO
+
+- Swarm mode never creates an agent: `ensure()` calls `engine.connect()` to put the broker itself on the freshly created per-agent overlay before `backend.create()` runs, and a swarm service task cannot be attached to another network at runtime, so the call returns `404 network <id> not found` for the full `realize_timeout` (measured 131 s to 133 s per attempt in run 37252453141, job 111587113070, `agent_failed` events in `services/agent-broker_agent-broker.log` of the swarm rescue bundle) and `backend.create()` is never reached. The CLI test then reads `no such service: agent-hermes-<id>` and every relayed prompt answers 502; `web-app-baserow`'s Playwright spec sees the same cause as HTTP 400. Compose is unaffected: its `network_driver` is `bridge`, local scope, and attaching a container works. `SwarmBackend.create()` already attaches the agent correctly through `TaskTemplate.Networks`, so only the broker's own attachment is impossible. Fixing it is a decision about the isolation boundary, not a code detail, and the operator has deferred it: listing the broker's own overlay in the agent's `Networks` at create time removes the hot-attach and keeps the diff small, but gives up network isolation between two owners' agents and leaves `API_SERVER_KEY` plus the per-agent volume as the only tenant separation; keeping the per-agent overlay instead means reaching the agent over a published port, which is cluster-wide reachable. Until it is decided, the swarm path is known broken and its jobs stay red.