fix(agent-room): rewrite migration to RESTORE 1:1 DMs, not relabel as chat

[samxu01]

Summary

Follow-up to #232. The previous migration script converted any agent-room pod with >2 members to type: 'chat'. Inspecting the actual offenders on api-dev showed every multi-member agent-room was an originally-1:1 DM polluted with rogue agents that auto-joined via ensureAgentInPod — exactly the bug PR #232's runtime guards close going forward. Relabel-to-chat legitimized the pollution; restoration is the correct action.

Live data that informed this

The three offending pods on dev all had the same shape: 1 host agent + 1 human + N rogue agents.

Pod	Host agent	Human	Rogue agents that auto-joined
commonly-bot (1)	commonly-bot	ls111	openclaw-{fakesam, tarik, ai-citation-strategist, tom}
commonly-bot (2)	commonly-bot	xcjsam	same 4
openclaw (fakesam)	openclaw-fakesam	xcjsam	openclaw-{ai-citation-strategist, tom, tarik}

None of these were ever multi-party chats. They were 1:1 DMs with intruders. Promoting them to chat would have made the bug permanent.

New migration logic

for each agent-room with members.length > 2:
  humans = members where User.isBot === false
  case humans.length === 1:
    keep [createdBy, the_human]; drop rogue agents
    stays type='agent-room'
  case humans.length === 0:
    agent↔agent DM. Trust insertion order — getOrCreateAgentRoom creates
    pods with [hostAgent, otherParty]; later auto-joins append.
    keep [members[0], members[1]]; drop the rest.
    stays type='agent-room'
  case humans.length >= 2:
    Was never a DM (multi-human surfaces are chat pods, not DMs).
    type → 'chat'. All members preserved.

Per ADR-001 §3.10, agent-room is exactly 2 members; the pair can be human + agent OR agent + agent, never 3+.

Also fixed

backend/routes/agentsRuntime.ts:516 — stale comment on POST /api/agents/runtime/room was still documenting the rejected "many humans × one agent office" framing. Now matches §3.10 and notes that the endpoint accepts only human JWT (agent↔agent DM creation has no agent-runtime endpoint yet — file a follow-up if needed).

Tests

backend/__tests__/unit/scripts/migrate-agent-room-multimember.test.js — 5 tests covering all three branches + dry-run + idempotency. Pod + User mocks so no real Mongo connection needed.

PASS __tests__/unit/scripts/migrate-agent-room-multimember.test.js
  ✓ 1 host agent + 1 human + N rogue agents → restore [host, human], stay agent-room
  ✓ 0 humans → agent↔agent DM, keep [members[0], members[1]] by insertion order
  ✓ 2+ humans → was never a DM, convert to chat, members preserved
  ✓ --dry mode reports a plan but does not save
  ✓ idempotent — pods with members.length <= 2 are not even returned by the cursor query

21/21 across the migration test + the inherited podController + ensureAgentInPod suites from #232.

Rollback safety

The previous migration script (#232) was never run on dev, so swapping in this rewrite doesn't require any rollback or compensating action. The runtime guards in #232 already prevent new pollution.

Test plan

• Unit tests for all three planner branches + dry-run + idempotency
• Manual kubectl exec ... migrate-agent-room-multimember.ts --dry against dev — review the plan against the live data before committing
• Re-run without --dry, verify commonly pod list --instance dev shows the three offending pods now have 2 members each and stayed agent-room type
• Verify the host agent can still post into its own DM (i.e. the ObjectId-equality fix from fix(agent-room): enforce 1:1 invariant + admin view + migrate legacy multi-member pods #232 plus this restored membership both hold)

🤖 Generated with Claude Code

[samxu01]

Self-review pass via code-reviewer subagent — addressed all findings in a3ef49526a.

Finding	Severity	Resolution
createdBy not in members would silently produce a 2-member pod with a ghost ID (no AgentInstallation, no User session matches)	Important	Added guard: skip with a warning if hostId ∉ memberIds in the human-branch. Pinned with a new test.
Orphan member IDs (no User row) handled correctly but not documented — next reader would think it was an oversight	Important	Added comment block above the humans filter spelling out the orphan semantics
Insertion-order claim asserted "Mongoose preserves order" without citing the evidence	Question	Comment now lists all three load-bearing facts: dmService.ts:290 creation shape, .push()-only mutations, no $set:{members:[...]} reorder (verified via grep)
Dedup comment misattributed which branch could collide	Nit	Comment removed; the dedupe is just defensive
Agent↔agent test didn't assert pod.type === 'agent-room'	Nit	Added explicit assertion
keepIds test used order-sensitive toEqual everywhere	Nit	Kept toEqual for the ordered keepIds (order is part of the contract — first kept is host) but switched dropIds to arrayContaining since drop order is not contract

Tests now 6/6 (was 5/5; +1 for the ghost-host edge case). All other findings from #232 already in scope and addressed there. CI status incoming via the Monitor.