fix(agent-room): enforce 1:1 invariant + admin view + migrate legacy multi-member pods

[lilyshen0722]

Summary

ADR-001 §3.10 says agent-rooms are personal 1:1 DMs — one user, one agent, no third party. The §3.10 amendment that corrected the original "N humans × 1 agent office" framing was documented but never enforced in code. Live data on api-dev showed agent-room pods with 5–6 members — a privacy/UX bug where what users perceive as a private DM was joinable by other people.

Surfaced during ADR-005 Phase 2 codex smoke (the commonly pod list output included agent-rooms with 5–6 members).

What changed

File	Change
backend/controllers/podController.ts	joinPod rejects any third-person join on agent-room (HTTP 403). getAllPods / getPodsByType skip the membership filter when caller is a global admin.
backend/services/agentIdentityService.ts	ensureAgentInPod refuses to add an agent to an agent-room when that agent isn't already a member — closes the auto-install path that was the most likely entry route for the multi-member legacy data.
backend/services/dmService.ts	Comment refresh — was still documenting the rejected N×1 "office" design.
backend/scripts/migrate-agent-room-multimember.ts (NEW)	Convert agent-room pods with 3+ members to type: 'chat'. Preserves messages, members, createdBy. Run with --dry to preview. Idempotent.
backend/__tests__/unit/controllers/podController.test.js	4 new tests: joinPod 403 on agent-room, chat-pod regression guard, admin bypass present, non-admin still filtered.
backend/__tests__/unit/services/agentIdentityService.ensureAgentInPod.test.js (NEW)	3 tests: refuse intruder agent, no-regression on chat pod, no-op for host agent re-running for its own DM.

Tests

PASS __tests__/unit/controllers/podController.test.js                12/12  (4 new)
PASS __tests__/unit/services/agentIdentityService.ensureAgentInPod   3/3   (all new)
PASS __tests__/unit/routes/pods.test.js                              5/5   (regression check)

20/20 across affected suites. No regression in adjacent test files.

Deploy steps after merge

1. Roll out the backend image (standard deploy).
2. Once running, trigger the migration on dev:

   kubectl exec -n commonly-dev <backend-pod> -- \
     npx ts-node backend/scripts/migrate-agent-room-multimember.ts --dry
   # review the offender list, then re-run without --dry
   

3. Verify commonly pod list --instance dev shows no agent-room pod with > 2 members.

Out of scope (filed as follow-ups)

• agent-admin type: ADR-001 §3.10 says this is legacy and slated for deprecation as LiteLLM session observability matures. This PR doesn't touch it; agent-admin can still have multiple admins (its design intent).
• Frontend admin UI for the new "view all agent-rooms" affordance — backend now supports it; UI surface is a separate ticket.
• A periodic invariant-check cron that warns if any agent-room ever drifts back to >2 members (defense in depth) — not added since the three write paths are now all guarded.

Test plan

• Unit tests for joinPod reject + chat regression
• Unit tests for ensureAgentInPod refuse + chat regression + self-noop
• Unit tests for getPodsByType admin bypass + non-admin filter
• Migration script idempotent + dry-run mode
• Manual smoke after merge: log in as a non-admin, attempt to join an existing agent-room owned by another user → expect 403
• Manual smoke after merge: log in as admin, hit /api/pods?type=agent-room → expect ALL agent-rooms returned regardless of membership
• Run migration against dev DB, verify commonly pod list shows no agent-room with >2 members afterward

🤖 Generated with Claude Code

[samxu01]

Self-review pass via code-reviewer subagent — addressed the critical finding + two important items in fbd93c7512.

Finding	Severity	Resolution
pod.members.includes(agentUser._id) uses JS ===, fails for Mongoose ObjectIds — host agent treated as "not a member" of its own room, the new agent-room guard fires, and null propagates to callers as "pod not found." Pre-existing bug; this PR exposed it.	Critical	Replace with .some((m) => m.equals?.(id) ?? String(m) === String(id)) — same pattern as removeAgentFromPod below. Test mock that hand-rolled the override deleted; new test uses real .equals()-bearing fakes so it would fail under the broken .includes().
getAllPods admin-bypass not directly tested (only getPodsByType was)	Important	Added parity case asserting an admin sees all agent-rooms via getAllPods
joinPod comment said "not even the creator" without clarifying that pod.createdBy for agent-rooms is the host agent (not a human user), so the creator-bypass in the invite-only block is effectively dead	Important	Tightened comment to make this explicit
Migration script silently changed pod.type = 'chat' without documenting downstream effects (UI tab move, privacy filter behavior, agentAutoJoinService scan visibility)	Important	Header now lists each consequence so the operator sees them before running on prod

Reviewer findings deliberately deferred:

• Q: 8+ other ensureAgentInPod callers ignore the return value — true, and now null can mean "refused" not just "pod not found." For most callers (install paths) the membership prerequisite is already enforced upstream, so the new refuse path closes a back door rather than silently breaking. Worth a follow-up audit but not blocking this PR.
• Q: Migration UX — the post-migration "5-member chat pod" is the simplest reasonable shape. All messages preserved, members preserved, just shows up under Chat instead of Agent DMs. Now documented in the script header.
• Q: agentAutoJoinService visibility post-migration — same point, now documented as a known consequence the operator should audit before running on prod.

Verdict: Request changes → critical + 3 important addressed. Tests now 21/21 across affected suites (was 20/20 before; +1 for the getAllPods admin parity case).