Skip to content

Fix Matrix configured two-person room routing#85137

Merged
joshavant merged 2 commits into
mainfrom
fix/matrix-two-person-room-routing
May 22, 2026
Merged

Fix Matrix configured two-person room routing#85137
joshavant merged 2 commits into
mainfrom
fix/matrix-two-person-room-routing

Conversation

@joshavant

@joshavant joshavant commented May 22, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Problem: Matrix rooms configured in channels.matrix.groups could still be classified as DMs when the room had exactly two members.
  • Solution: Let explicit Matrix room config veto DM classification before stale m.direct or the strict two-member fallback can route the event as a DM.
  • What changed: Wired the Matrix direct-room tracker to consult exact room config and resolved alias config, with regression coverage for stale m.direct and pre-seed fallback paths.
  • What did NOT change (scope boundary): Wildcard room config does not override DM classification, and generic strict-DM evidence/promotion behavior is unchanged.

Motivation

  • Fixes a live Matrix routing bug where unmentioned messages in a configured two-person room could bypass mention gating by being treated as DMs.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor required for the fix
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

Real behavior proof (required for external PRs)

Behavior addressed: Matrix two-person rooms explicitly configured as rooms no longer bypass mention gating via DM classification.
Real environment tested: AWS Crabbox cbx_1098b2400fe1, run run_d7af6f2a55c9; Linux Node 24.15.0; Docker Tuwunel ghcr.io/matrix-construct/tuwunel:v1.5.1; OpenClaw gateway with Matrix QA live harness and mock OpenAI provider.
Exact steps or command run after this patch: node scripts/crabbox-wrapper.mjs run --provider aws --idle-timeout 90m --ttl 180m --timing-json --preflight --script-stdin, which installed dependencies, ran pnpm build, booted Tuwunel, provisioned two configured Matrix group rooms, started the gateway, sent mentioned and unmentioned messages, and observed Matrix sync replies.
Evidence after fix: OPENCLAW_85017_FIX_PROOF_SUMMARY reported fixed: true; the two-person configured room had joined count 2, sutMemberIsDirect: null; mentioned message replied with marker MATRIX_QA_85017_MENTION_46F1B779; unmentioned two-person room message had matched: false; unmentioned three-person control had matched: false.
Observed result after fix: Mentioned room messages still trigger, while unmentioned messages in a configured two-person Matrix room stay silent instead of being routed as DMs.
What was not tested: A public Matrix homeserver outside the disposable Tuwunel QA harness.
Before evidence (optional but encouraged): AWS Crabbox repro on current main cbx_a29749d91e7d, run run_cec1acaaab88, showed the same two-person configured room replying to an unmentioned message while the three-person control stayed silent.

Root Cause (if applicable)

  • Root cause: Matrix DM classification ran before room policy and treated strict two-member rooms as DMs, so explicit room config and mention gating were never applied.
  • Missing detection / guardrail: The direct-room tracker did not have coverage for explicit room config vetoing stale m.direct or pre-seed strict fallback classification.
  • Contributing context (if known): Matrix rooms can be both two-member conversations and explicitly configured group/room surfaces; operator config needs to win over heuristic DM inference.

Regression Test Plan (if applicable)

  • Coverage level that should have caught this:
    • Unit test
    • Seam / integration test
    • End-to-end test
    • Existing coverage already sufficient
  • Target test or file: extensions/matrix/src/matrix/monitor/direct.test.ts, extensions/matrix/src/matrix/monitor/index.test.ts.
  • Scenario the test should lock in: Exact and alias Matrix room config veto stale m.direct and strict two-member fallback before DM routing.
  • Why this is the smallest reliable guardrail: The bug is at the Matrix monitor/direct-room classification seam, so these tests pin the classification precedence without needing a full gateway boot for every case.
  • Existing test that already covers this (if any): Adjacent direct-room and room-config tests covered strict membership and match-source behavior, but not this precedence path.
  • If no new test is added, why not: N/A.

User-visible / Behavior Changes

Configured Matrix rooms now follow room mention-gating even when the room has exactly two members.

Diagram (if applicable)

Before:
Matrix room message -> two-member DM classifier -> DM route -> mention gate skipped

After:
Matrix room message -> explicit room config veto -> room route -> mention gate applies

Security Impact (required)

  • New permissions/capabilities? No
  • Secrets/tokens handling changed? No
  • New/changed network calls? No
  • Command/tool execution surface changed? No
  • Data access scope changed? No
  • If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

  • OS: Linux on AWS Crabbox
  • Runtime/container: Node 24.15.0, Docker Tuwunel ghcr.io/matrix-construct/tuwunel:v1.5.1
  • Model/provider: mock OpenAI provider via QA live gateway
  • Integration/channel (if any): Matrix
  • Relevant config (redacted): groupPolicy: "open", configured groups for a 2-member room and a 3-member control room, each with requireMention: true; Matrix DM allowlist enabled for the driver.

Steps

  1. Boot disposable Tuwunel and provision Matrix driver, SUT, and observer users.
  2. Create a configured two-person group room with driver and SUT, and a configured three-person control room.
  3. Start the OpenClaw gateway with the Matrix account config generated from those room IDs.
  4. Send a mentioned message to the two-person room.
  5. Send unmentioned messages to both configured rooms.

Expected

  • The mentioned two-person room message receives a SUT reply.
  • The unmentioned two-person room message receives no SUT reply.
  • The unmentioned three-person control receives no SUT reply.

Actual

  • Matches expected in AWS Crabbox run run_d7af6f2a55c9.

Evidence

  • Failing test/log before + passing after
  • Trace/log snippets
  • Screenshot/recording
  • Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

  • Verified scenarios: Focused Matrix tests passed on AWS Crabbox; live Matrix proof passed on AWS Crabbox with the original two-person-room repro shape.
  • Edge cases checked: stale m.direct, strict two-member fallback before DM cache seed, exact room IDs, resolved alias config, wildcard config not overriding DM classification.
  • What you did not verify: A public Matrix homeserver outside the disposable Tuwunel QA harness.

Review Conversations

  • I replied to or resolved every bot review conversation I addressed in this PR.
  • I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

  • Backward compatible? Yes
  • Config/env changes? No
  • Migration needed? No
  • If yes, exact upgrade steps: N/A

Risks and Mitigations

  • Risk: Alias-configured rooms need room alias metadata before classification.
    • Mitigation: The alias lookup is only used when alias keys are present in Matrix room config, and exact room ID config avoids the extra lookup.

@openclaw-barnacle openclaw-barnacle Bot added channel: matrix Channel integration: matrix size: S maintainer Maintainer-authored PR labels May 22, 2026
@clawsweeper

clawsweeper Bot commented May 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Summary
This PR makes Matrix direct-room classification consult explicit room config before stale m.direct or strict two-member fallback routing, and adds focused Matrix monitor regression tests plus a changelog entry.

Reproducibility: yes. The PR body gives a current-main Crabbox repro where an unmentioned configured two-person Matrix room replied, and current source shows DM classification runs before room config and mention gating.

PR rating
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Summary: Strong proof and a small, well-targeted Matrix routing patch; the only material concern is the intentional compatibility/message-delivery change maintainers need to accept.

What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Real behavior proof
Sufficient (live_output): The PR body includes after-fix Crabbox live Matrix proof with exact environment, command, before repro run, observed markers, and no-match results for unmentioned configured two-person room traffic.

Risk before merge

  • Merging intentionally changes configured two-person Matrix rooms from DM routing to room routing, so existing setups that configured such a room but relied on unmentioned DM-style replies may go silent until they set autoReply: true or mention the bot.
  • The live proof uses disposable Tuwunel/Crabbox rather than a public Matrix homeserver, though it exercises the relevant Matrix sync and gateway path.

Maintainer options:

  1. Accept the configured-room behavior change (recommended)
    Merge after Matrix-owner review acknowledges that explicit room config now wins over DM heuristics and unmentioned messages may stop unless operators configure room auto-reply.
  2. Add upgrade-facing Matrix guidance first
    Before merge, add a short docs or release-note note telling operators to use autoReply: true for configured two-person rooms that should keep responding without mentions.
  3. Pause for a broader Matrix routing policy decision
    If maintainers are unsure whether configured rooms should always override DM heuristics, pause this PR and resolve the policy on the linked Matrix issue first.

Next step before merge
No repair job is needed from this review; the patch has no blocking findings and should proceed through maintainer merge judgment and normal checks.

Security
Cleared: No new security or supply-chain concern was found; the patch narrows Matrix routing so configured-room mention policy is applied and does not touch secrets, dependencies, workflows, or command execution.

Review details

Best possible solution:

Land the configured-room veto with Matrix-owner approval, preserving wildcard and fresh-DM fallback behavior while documenting the intentional operator-visible routing change through the changelog.

Do we have a high-confidence way to reproduce the issue?

Yes. The PR body gives a current-main Crabbox repro where an unmentioned configured two-person Matrix room replied, and current source shows DM classification runs before room config and mention gating.

Is this the best way to solve the issue?

Yes. Moving an exact configured-room veto into the direct tracker is the narrow owner-boundary fix and the tests preserve wildcard/non-configured DM fallback behavior.

Label changes:

  • add P1: The PR fixes a Matrix channel workflow where configured room mention gating can be bypassed by DM misclassification.
  • add merge-risk: 🚨 compatibility: The patch intentionally changes behavior for existing configured two-person Matrix rooms that previously received DM-style unmentioned replies.
  • add merge-risk: 🚨 message-delivery: The routing change can suppress unmentioned messages in affected configured rooms, which is the intended fix but still a delivery-impacting merge risk.
  • add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix Crabbox live Matrix proof with exact environment, command, before repro run, observed markers, and no-match results for unmentioned configured two-person room traffic.
  • add rating: 🦞 diamond lobster: Current PR rating is 🦞 diamond lobster because proof is 🦞 diamond lobster, patch quality is 🦞 diamond lobster, and Strong proof and a small, well-targeted Matrix routing patch; the only material concern is the intentional compatibility/message-delivery change maintainers need to accept.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes after-fix Crabbox live Matrix proof with exact environment, command, before repro run, observed markers, and no-match results for unmentioned configured two-person room traffic.

Label justifications:

  • P1: The PR fixes a Matrix channel workflow where configured room mention gating can be bypassed by DM misclassification.
  • merge-risk: 🚨 compatibility: The patch intentionally changes behavior for existing configured two-person Matrix rooms that previously received DM-style unmentioned replies.
  • merge-risk: 🚨 message-delivery: The routing change can suppress unmentioned messages in affected configured rooms, which is the intended fix but still a delivery-impacting merge risk.
  • rating: 🦞 diamond lobster: Current PR rating is 🦞 diamond lobster because proof is 🦞 diamond lobster, patch quality is 🦞 diamond lobster, and Strong proof and a small, well-targeted Matrix routing patch; the only material concern is the intentional compatibility/message-delivery change maintainers need to accept.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes after-fix Crabbox live Matrix proof with exact environment, command, before repro run, observed markers, and no-match results for unmentioned configured two-person room traffic.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix Crabbox live Matrix proof with exact environment, command, before repro run, observed markers, and no-match results for unmentioned configured two-person room traffic.

Acceptance criteria:

  • node scripts/run-vitest.mjs extensions/matrix/src/matrix/monitor/direct.test.ts extensions/matrix/src/matrix/monitor/index.test.ts extensions/matrix/src/matrix/direct-room.test.ts

What I checked:

Likely related people:

  • @gumadeiras: Recent local history shows repeated Matrix QA/live transport and Matrix plugin work near the affected channel behavior. (role: recent Matrix QA and channel contributor; confidence: medium; commits: 25445a9f2e86, 94081d886336, 2bfd808a8311; files: extensions/matrix/src, extensions/matrix/src/matrix/monitor)
  • @steipete: Recent history includes many Matrix monitor/test performance and release commits, plus current release/changelog ownership around Matrix changes. (role: recent adjacent Matrix maintainer; confidence: medium; commits: 605cb60586eb, 2a0a498b0d26, e2c92be90b06; files: extensions/matrix/src/matrix/monitor, CHANGELOG.md)
  • Sarah Fortune: Current-main blame for the direct tracker, handler, and room config resolver points to a broad recent commit that recreated the Matrix monitor files in this checkout. (role: recent area contributor; confidence: low; commits: 4f80cc1943b9; files: extensions/matrix/src/matrix/monitor/direct.ts, extensions/matrix/src/matrix/monitor/handler.ts, extensions/matrix/src/matrix/monitor/rooms.ts)
  • @w-sss: The linked issue review identifies a prior merged direct-room classification fix as partial precedent for the same is_direct and strict-DM area. (role: prior DM classification fix author; confidence: medium; commits: 2b2edaa01db5; files: extensions/matrix/src/matrix/direct-room.ts, extensions/matrix/src/matrix/monitor/direct.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 777a113973e9.

@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P1 High-priority user-facing bug, regression, or broken workflow. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 message-delivery 🚨 May drop, duplicate, misroute, suppress, or wrongly target messages. labels May 22, 2026
@clawsweeper

clawsweeper Bot commented May 22, 2026

Copy link
Copy Markdown
Contributor

ClawSweeper PR egg

✨ Hatched: ✨ glimmer Sunspot Patch Peep

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

  • Merged PRs are hatchable.
  • Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
  • Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: ✨ glimmer.
Trait: sparkles near resolved comments.
Image traits: location merge queue dock; accessory little merge flag; palette charcoal, cyan, and signal green; mood patient; pose balancing on a branch marker; shell translucent glimmer shell; lighting calm overcast light; background soft code-shaped tiles.
Share on X: post this hatch
Copy: My PR egg hatched a ✨ glimmer Sunspot Patch Peep in ClawSweeper.

What is this egg doing here?
  • Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
  • The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
  • Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
  • The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
  • Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

@joshavant joshavant merged commit 1f9ebb9 into main May 22, 2026
137 of 147 checks passed
@joshavant joshavant deleted the fix/matrix-two-person-room-routing branch May 22, 2026 00:40
This was referenced May 22, 2026
Closed
Closed
@clawsweeper clawsweeper Bot mentioned this pull request May 22, 2026
Open
@Haderach-Ram Haderach-Ram mentioned this pull request May 22, 2026
Open
@github-actions github-actions Bot mentioned this pull request May 22, 2026
Open
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 24, 2026
@joshavant @SebTardif
Fix Matrix configured two-person room routing (openclaw#85137)
8eef951 
* Fix Matrix configured room DM routing

* Add Matrix room routing changelog
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 24, 2026
@joshavant @SebTardif
Fix Matrix configured two-person room routing (openclaw#85137)
3f06e41 
* Fix Matrix configured room DM routing

* Add Matrix room routing changelog
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 24, 2026
@joshavant @SebTardif
Fix Matrix configured two-person room routing (openclaw#85137)
8e84c8d 
* Fix Matrix configured room DM routing

* Add Matrix room routing changelog
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 24, 2026
@joshavant
Fix Matrix configured two-person room routing (openclaw#85137)
2ba0a48 
* Fix Matrix configured room DM routing

* Add Matrix room routing changelog
galiniliev pushed a commit to galiniliev/openclaw that referenced this pull request May 25, 2026
@joshavant
Fix Matrix configured two-person room routing (openclaw#85137)
8310631 
* Fix Matrix configured room DM routing

* Add Matrix room routing changelog
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 26, 2026
@joshavant @SebTardif
Fix Matrix configured two-person room routing (openclaw#85137)
5ac186b 
* Fix Matrix configured room DM routing

* Add Matrix room routing changelog
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 26, 2026
@joshavant @SebTardif
Fix Matrix configured two-person room routing (openclaw#85137)
b0d3110 
* Fix Matrix configured room DM routing

* Add Matrix room routing changelog
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 26, 2026
@joshavant @SebTardif
Fix Matrix configured two-person room routing (openclaw#85137)
1825afa 
* Fix Matrix configured room DM routing

* Add Matrix room routing changelog
@lukeboyett lukeboyett mentioned this pull request May 28, 2026
Open
jameslcowan pushed a commit to jameslcowan/openclaw that referenced this pull request Jun 2, 2026
@joshavant
Fix Matrix configured two-person room routing (openclaw#85137)
cea1aec 
* Fix Matrix configured room DM routing

* Add Matrix room routing changelog
SYU8384 pushed a commit to SYU8384/openclaw that referenced this pull request Jun 3, 2026
@joshavant
Fix Matrix configured two-person room routing (openclaw#85137)
f132c9c 
* Fix Matrix configured room DM routing

* Add Matrix room routing changelog
sablehead pushed a commit to sablehead/openclaw that referenced this pull request Jun 10, 2026
@joshavant
Fix Matrix configured two-person room routing (openclaw#85137)
c61b4f0 
* Fix Matrix configured room DM routing

* Add Matrix room routing changelog
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

channel: matrix Channel integration: matrix maintainer Maintainer-authored PR merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 message-delivery 🚨 May drop, duplicate, misroute, suppress, or wrongly target messages. P1 High-priority user-facing bug, regression, or broken workflow. proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. size: S status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

1 participant

@joshavant