Summary

• Problem: Matrix streaming: "partial" and blockStreaming: true were not just incompatible in config wiring; async block delivery could also desynchronize draft offsets and assistant-message generations.
• Why it matters: under slow Matrix sends or fast model output, later partials could be sliced against stale boundaries, leading to duplicated, dropped, rewound, or cross-message draft text.
• What changed: Matrix now keeps partial previews for the active block, preserves completed block messages when block streaming is enabled, queues logical block boundaries before async delivery, and carries source assistantMessageIndex metadata so delayed block flushes stay attached to the correct message generation.
• What did NOT change (scope boundary): no config shape change, no other channel behavior change, no transport/protocol redesign, and no change to default streaming: "off" behavior.

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 #
• Related #
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause 1: the Matrix handler originally forced disableBlockStreaming=true whenever partial drafts were enabled, so explicit channels.matrix.blockStreaming intent was ignored.
• Root cause 2: once shared block streaming was re-enabled, Matrix draft bookkeeping still followed transport completion instead of logical block boundaries, so async block sends could leave onPartialReply slicing against stale offsets.
• Root cause 3: text_end block flushes can be deferred past onAssistantMessageStart, so old block boundaries could be stamped with the next assistant message generation unless the source generation is captured and routed through.
• Missing detection / guardrail: coverage only checked option wiring, not block/draft/final sequencing, delayed block drain ordering, or late block boundaries crossing assistant-message starts.
• Prior context (git blame, prior PR, issue, or refactor if known): this extends earlier Matrix draft-streaming and block-streaming behavior rather than introducing a new delivery model.
• If unknown, what was ruled out: no evidence of a Matrix transport-only bug; the fault was in local reply-state bookkeeping and metadata routing.

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 tests/files:
  • extensions/matrix/src/matrix/monitor/handler.test.ts
  • src/auto-reply/reply/dispatch-from-config.test.ts
  • src/agents/pi-embedded-subscribe.subscribe-embedded-pi-session.emits-block-replies-text-end-does-not.test.ts
• Scenarios locked in:
  • partial previews plus explicit Matrix block streaming
  • completed-block preservation plus active-draft finalization
  • delayed block delivery with later partials already received
  • multiple queued block boundaries
  • assistant-message start arriving before an older text_end block flush drains
  • source assistantMessageIndex propagation into block-boundary queueing
• Why this is the smallest reliable guardrail: the bug spans producer -> shared dispatch -> Matrix consumer, so coverage has to pin each routing seam plus the Matrix state machine.

User-visible / Behavior Changes

• Matrix can now safely combine streaming: "partial" with blockStreaming: true.
• The active assistant block stays a live editable draft.
• Completed blocks can remain preserved as separate Matrix messages.
• Delayed block sends no longer rewind or corrupt the next draft block or the next assistant message's draft when boundaries arrive late.

Diagram (if applicable)

Before:
[user prompt]
  -> [draft current block]
  -> [async block send lags]
  -> [later partial slices from stale offset]
  -> [duplicate/rewind/drop text possible]

After:
[user prompt]
  -> [draft current block]
  -> [logical block boundary queued immediately]
  -> [completed block preserved when delivery drains]
  -> [next draft starts from queued boundary]
  -> [late old block still routed to original assistant message generation]

Security Impact (required)

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

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22+, pnpm
• Model/provider: N/A
• Integration/channel (if any): Matrix
• Relevant config (redacted): channels.matrix.streaming: "partial", channels.matrix.blockStreaming: true

Steps

1. Enable Matrix partial draft streaming and block streaming.
2. Trigger an assistant reply with multiple blocks or a delayed text_end block flush.
3. Let later partials or a new assistant-message start arrive before the older block delivery drains.
4. Observe draft/block sequencing.

Expected

• Active block uses a live editable draft.
• Completed blocks remain preserved as separate messages when block streaming is enabled.
• Later partials start from the correct logical block boundary.
• Late block flushes remain associated with the original assistant message generation.

Actual

• Covered by the updated targeted tests in this PR.

Evidence

Attach at least one:

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

Human Verification (required)

• Verified scenarios: reviewed producer -> dispatch -> Matrix routing, updated Matrix/docs contracts, ran focused regressions for queued boundaries, late text_end, and message-generation propagation.
• Edge cases checked: partial previews with block streaming off, partial previews with block streaming on, delayed block delivery, multiple queued boundaries, new assistant message before old block drain.
• What you did not verify: live Matrix homeserver/manual room repro in this branch.

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/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: the state machine is more explicit now because it has to track queued block boundaries and source generations.
  • Mitigation: keep Matrix-specific policy inside the Matrix plugin, keep the shared seam additive (onBlockReplyQueued + optional metadata), and pin the routing contract with targeted tests.