Summary

• Problem: ACP thread-bound session spawn reused a lossy groupId as the transport target, which lowercased mixed-case Matrix room ids and dropped parent conversation context for thread binds.
• Why it matters: Matrix ACP binds could fail from top-level rooms or existing threads, while other channels rely on the same core seam.
• What changed: src/agents/acp-spawn.ts now resolves full conversation refs through the plugin seam, keeps canonical to authoritative, preserves parentConversationId for thread binds, and keeps channel-specific fallback behavior intact.
• What did NOT change (scope boundary): session/group metadata normalization and broader groupId semantics across policy/config code were not redesigned here.

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

• Closes [Bug]: Matrix ACP thread-bound sessions fail because room IDs are lowercased during session/binding routing #63828
• Related [Bug]: Matrix ACP thread-bound sessions fail because room IDs are lowercased during session/binding routing #63828
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: ACP thread spawn collapsed canonical to and fallback groupId into the same value before calling resolveInboundConversation(), so case-sensitive Matrix room ids were lowercased and parent conversation refs for thread binds were lost.
• Missing detection / guardrail: ACP spawn lacked a seam test that exercised mixed-case Matrix room ids and existing-thread binds through the generic plugin contract.
• Contributing context (if known): groupId is still overloaded in core for policy/session metadata, so the ACP seam needed to prefer canonical routing data without changing broader groupId behavior for other channels.

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: src/agents/acp-spawn.test.ts
• Scenario the test should lock in: ACP thread=true preserves canonical Matrix room casing from both top-level rooms and existing Matrix threads while leaving LINE and Telegram behavior unchanged.
• Why this is the smallest reliable guardrail: the regression lives at the generic ACP spawn-to-plugin seam, not inside Matrix-only binding code.
• Existing test that already covers this (if any): existing Discord/Telegram ACP spawn tests cover neighboring thread-binding behavior.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Matrix ACP thread-bound session spawns now bind correctly when the room id casing differs from persisted groupId, including spawns launched from existing Matrix threads.

Diagram (if applicable)

Before:
[sessions_spawn thread=true] -> [ACP spawn uses lowercased groupId for to + conversationId]
-> [Matrix resolves wrong parent room] -> [bind/send can fail]

After:
[sessions_spawn thread=true] -> [ACP spawn passes canonical to + fallback conversationId]
-> [plugin resolves full conversation ref] -> [bind/send uses correct room + thread context]

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:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local repo dev environment
• Model/provider: N/A
• Integration/channel (if any): Matrix ACP thread bindings
• Relevant config (redacted): channels.matrix.threadBindings.enabled=true

Steps

1. Start from a Matrix room with a mixed-case room id and persisted lowercased groupId.
2. Trigger sessions_spawn({ runtime: "acp", thread: true }) from the room or from an existing Matrix thread.
3. Observe the created ACP binding target.

Expected

• ACP spawn binds using the canonical Matrix room id, preserving parent conversation context for thread binds.

Actual

• Before this fix, ACP spawn could bind/send using the lowercased room id or lose the parent room when launched from an existing thread.

Evidence

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

Human Verification (required)

• pnpm test src/agents/acp-spawn.test.ts
• pnpm check