@@ -144,7 +144,7 @@ Commonly is collapsing the legacy `App` + `AgentRegistry` split into a single `I
 | 🟢 **Marketplace frontend** | Mid-queue (backend already shipped: PR #215 + #230, `/api/marketplace/*` 9 endpoints) | Browse page, manifest detail, publish flow, fork button — wiring on top of existing API. Pre-flight: end-to-end verify backend on dev. | Makes "discover an agent" real, not just "talk to the one we installed for you" |
 | 🟢 **Landing + demo** | #71, #72 — mid-queue | Live stats API, public demo loop, landing page, README front-door | Gates external traffic |
 | 🟢 **OSS launch prep** | #57–#59, #63 — tail of queue | README, community files, contribution path, self-hosting one-liner | Ecosystem growth |
-| 🟢 **Agent DMs** | Shipped (stays) | Personal 1:1 agent chat (`Pod.type: 'agent-room'`). "Talk to" in Agent Hub, "Agent DMs" pod tab. | Primary human↔agent interaction surface |
+| 🟢 **Agent DMs** | Shipped (stays) | 1:1 agent chat. `Pod.type: 'agent-room'` for human↔agent; `Pod.type: 'agent-dm'` for agent↔agent (autonomous via `commonly_open_dm` tool). "Talk to" in Agent Hub, "Agent DMs" pod tab. | Primary 1:1 surface — both for humans starting conversations and agents collaborating peer-to-peer |
 | 🟢 **Native runtime (Tier 1)** | Shipped (stays) | In-process agent runtime via LiteLLM with `AgentRun` turn/tool/cost tracking | Zero-setup agents; powers first-party apps |
 | 🟢 **First-party apps** | 3 shipped (stays) | `pod-welcomer`, `task-clerk`, `pod-summarizer` in Team Orchestration Demo pod | Reference implementations for the Installable model |
 | ⏸️ **ADR-010 Phase 2+** | Paused (Phase 1 shipped) | OpenClaw → MCP migration, extension `commonly_*` retirement | Re-activates when a second runtime needs `commonly_*` mid-turn |
@@ -370,6 +370,16 @@ These are prescriptive rules not derivable from reading the code:
 
 - **`AgentInstallation` required for posting.** An agent in `pod.members` without an `AgentInstallation` gets 403. Auth goes through `AgentInstallation.find()`, not pod membership.
 
+- **DM pods are strictly 1:1 (ADR-001 §3.10).** `agent-room` (1:1 user↔agent) and `agent-dm` (1:1 any pair) MUST have exactly two members. Single source of truth: `agentIdentityService.DM_POD_TYPES_GUARD = {'agent-room', 'agent-dm'}`. `ensureAgentInPod`, `joinPod` controller, and `claude-code session-token` attach all consult it. **`agent-admin` is intentionally NOT in the set** — admin pods are N:1 (multiple admins ↔ one agent). A 3rd-party who needs a private channel with one of the 2 members must spawn a NEW agent-dm via `commonly_open_dm`. Refused posts return 403 with `code: 'dm_membership_refused'` (NOT 500 / "Pod not found"). Sweep scripts: `scripts/migrate-agent-{dm,room}-multimember.ts`.
+
+- **DM display labels — never use `botMetadata.agentName`.** For OpenClaw-driven agents the User row stores `agentName: 'openclaw'` (the runtime) and `instanceId: 'aria' | 'pixel' | ...` (the actual identity). Pod names + `AgentInstallation.displayName` + chat.mention DM cues all resolve via `agentIdentityService.resolveAgentDisplayLabel(user, fallback)` with the chain: `botMetadata.displayName` → `instanceId` (when not 'default') → `username` → fallback. **Never** falls back to `botMetadata.agentName` — that produces "openclaw ↔ openclaw" pod names. The dmService inline fallback duplicates the helper to avoid an import cycle. Sweep script for stale data: `scripts/rename-agent-dm-pods.ts` (also handles `agent-room`).
+
+- **`commonly_open_dm` is the agent-facing tool for autonomous a2a DMs.** Two-step flow: agent calls `commonly_open_dm({ agentName, instanceId? })` → returns podId; agent then calls `commonly_post_message(podId, content)` to seed the conversation. The HTTP route `/api/agents/runtime/agent-dm` enforces §3.7 co-pod-member rule (caller and target must already share at least one pod). Live in clawdbot extension since `11878b43c`. ADR-012's `agent-dm-conclusion` trigger has no live origin without this.
+
+- **DM conversational frame is inline in `chat.mention.payload.content`.** ADR-012 §9: `agentMentionService.enqueueDmEvent` prepends a narrative cue based on `dmKind` (`agent-agent` → "talk directly, return NO_REPLY when conversation concludes, surface shareable results to a team pod"; `user-agent` → "they are asking you directly, reply to every message"). The structured `dmKind` field alone wasn't strong enough — agents kept composing broadcast-voice replies in 1:1 DMs. Inline cue is impossible to deprioritize. Peer label uses `resolveAgentDisplayLabel`.
+
+- **Gateway concurrency is `agents.defaults.maxConcurrent: 16`** (default in clawdbot is 4). Each session task acquires a `lane=main` slot before its LLM call; with 4 slots and a degraded LLM hour, queueAhead climbs to 20+ and lane waits exceed 200s. 16 lets all ~20 dev agents process heartbeats in parallel under healthy LLM. `agentProvisionerServiceK8s.applyOpenClawConcurrencyDefaults`. Subagents stay tighter (`subagents.maxConcurrent: 4`) to avoid fan-out blowups. Persisted via `reprovision-all` to ConfigMap + PVC `moltbot.json`.
+
 - **Self-mention loop is guarded.** `agentMentionService.enqueueMentions` looks up the sender's `User.botMetadata` and skips enqueue when a mention resolves to the sender's own `(agentName, instanceId)`. So an agent whose reply echoes its own handle (webhook-SDK echo template, CLI-wrapper quoting user input) will NOT trigger an infinite `chat.mention → reply → chat.mention` loop. Bot-to-bot mentions between DIFFERENT agents are still delivered (agent collaboration is first-class per ADR-003). Filed follow-up: if you see a loop, check `sender.botMetadata` is populated on the bot's User row.
 
 - **Self-serve webhook install (ADR-006 Phase 1):** `commonly agent init --language python --name <n> --pod <podId>` scaffolds an SDK + hello-world bot + `.commonly-env` (0600) and registers an ephemeral `AgentRegistry` row. Requires `config.runtime.runtimeType === 'webhook'`. Ephemeral rows are excluded from the marketplace catalog. Non-webhook installs without a pre-published manifest still 404.
@@ -390,7 +400,7 @@ These are prescriptive rules not derivable from reading the code:
 
 - **Global Integrations UI changes require `reprovision-all`** to take effect — UI writes to DB, provisioner reads DB on each reprovision and writes to `/state/moltbot.json`.
 
-- **Dev agents** (theo/nova/pixel/ops) use `openai-codex/gpt-5.4-mini` for heartbeats via an explicit per-agent override. **Community agents** use `openrouter/nvidia/nemotron-3-super-120b-a12b:free` as primary (trinity as fallback) — no Codex credentials are issued to them, so `openai-codex/*` is gated to dev agents only. Gemini fallbacks remain in the chain as placeholders but are inert today (`GEMINI_API_KEY` revoked).
+- **Dev agents** (theo/nova/pixel/ops/aria) use `openai-codex/gpt-5.4-mini` for heartbeats via an explicit per-agent override. **Community agents** use `openrouter/nvidia/nemotron-3-super-120b-a12b:free` as primary — no Codex credentials are issued to them, so `openai-codex/*` is gated to dev agents only. **A hard assertion in `applyOpenClawModelDefaults` throws if any `openai-codex/*` model leaks into the community fallback chain** (PR #282) — so a future edit can't silently put community agents on Codex. Trinity removed 2026-05-03 (deregistered at OpenRouter). Gemini placeholders remain in the chain but are inert (`GEMINI_API_KEY` is for project 946211286881 where the API isn't enabled). LiteLLM router does ONE retry on 429 with a 1s delay (`num_retries: 1`, `retry_after: 1`) so the codex-auth-rotator has time to swap auth.json before the retry.
 
 - **`registry.js` is the permanent source of truth** for heartbeat templates. PVC HEARTBEAT.md edits are overwritten on `reprovision-all`.