--- spec: docs/specs/ui/requirements/message-queue-auto-merge.md created: 2026-08-12 status: completed --- # Implementation Plan: Automatically Merge Consecutive Queued Messages ## Overview Add a default-on, install-wide automatic-merge setting without changing the manual merge switch. Build the strict tail-compatibility mutation first, route ordinary admission and staged attachment admission through it safely, then add settings persistence and UI. Finish with desktop/mobile E2E coverage and public documentation. --- ## Backend ### Automatic tail-merge contract - Add a repository operation in `apps/backend/internal/orchestrator/messagequeue/repository.go` that targets one newly inserted source ID and its immediate predecessor. It returns the surviving target plus whether a fold occurred; incompatibility is a normal `false` result, not `ErrNoMergeTarget`. - Implement it under the existing per-session lock in `repository_memory.go` and as one transaction in `repository_sqlite.go` (the database-backed implementation also serves the env-gated Postgres suite). Select by source ID and session, select only the greatest lower position, compute the complete candidate, update the target, and delete the exact source. A missing/drained source never causes a search for another source. - Keep manual `MergeIntoAbove` and `mergeAllowed` unchanged. Add automatic-only helpers in `merge.go`: - source compatibility: same task/model/plan mode; user identities equal and non-reserved, or agent identities equal with one identical non-empty `sender_task_id`; lifecycle/workflow/server/clarification rows excluded; - non-additive metadata comparison after normalizing JSON-round-tripped map values; - stable entity-reference and context-file unions; - combined attachment count/byte validation using the same limits and byte accounting as send-now; - content joining that adds `\n\n` only when both bodies are non-empty. - Preserve the target's immutable fields and target-then-source order. Any mismatch or limit overflow leaves both rows unchanged and returns a skipped result. ### Admission integration - Extend `messagequeue.Service` in `service.go` with a separate atomic `autoMergeEnabled` value, defaulting to true, plus getters/setters. Do not reuse `mergeEnabled`; test all four switch combinations. - Within `QueueMessageWithMetadata`, snapshot capacity and automatic-merge state under `WithSessionAdmission`, perform the existing capped insert, then attempt the repository fold. Capacity remains an admission prerequisite. Return the surviving target on success and the source on skip. - Treat a post-insert automatic-fold storage error as degraded success: the transaction leaves the accepted source separate, the service logs the failure, and callers do not receive an error that encourages a duplicate retry. - Add a narrow deferred-finalization path for user WebSocket admissions that contain staged file-backed attachments. Hold `WithSessionAdmission` across insertion, claim, fold, and rollback so no later admission can merge into the provisional source. `queue_handlers.go` must insert a distinct source first, claim its attachments, and only then finalize the snapshotted automatic-merge decision. On claim failure, the existing rollback removes only that source ID. Inline attachments can use ordinary admission. - Preserve exact-ID consumers. `QueueAndInterruptForPeerMessage` and `message_task_kandev` use the returned surviving ID, so an immediate parent interrupt takes the complete merged entry. Workflow/coalesce, restoration, explicit append, clarification, and reserved lifecycle paths remain excluded by their APIs or compatibility checks. - Publish `message.queue.status_changed` only after the final merge-or-separate state is known. Do not add `auto_merge_enabled` to `QueueStatus`; the queue panel has no setting control. ### Persistent settings and startup wiring - Extend `apps/backend/internal/system/queuesettings/types.go` with `AutoMergeEnabled` on `Settings`, `SettingsPatch`, and `Effective`. Apply and validate it like the independent manual merge boolean. - Extend `store.go`'s pointer-backed legacy decoder so an omitted `auto_merge_enabled` becomes true while an explicit false survives. Saving writes the normalized three-field object. - Extend `resolver.go` and `service.go` so GET/PATCH round-trip the field, partial updates preserve both other values, max-capacity environment locks do not block an auto-only patch, persistence precedes live apply, and the queue target receives all three effective values. In particular, an auto-only or manual-only PATCH under an environment capacity override must reapply the resolved environment capacity, not the lower persisted capacity. - In `apps/backend/internal/backendapp/orchestrator.go`, resolve and apply the saved automatic setting before the orchestrator accepts work. Update `message_queue_settings_test.go`, `system_routes_test.go`, and `internal/system/queuesettings/queuesettings_test.go` for default, upgrade, explicit false, partial PATCH, environment lock, restart, and live-apply cases. --- ## Frontend ### Settings API and types - Add `auto_merge_enabled` to `MessageQueueSettingsValue` in `apps/web/lib/types/system.ts`. The existing partial patch type then accepts an auto-only update without changing the HTTP client contract. - Update `apps/web/lib/api/domains/settings-api.test.ts` fixtures and assertions to prove the field is decoded and sent alone. ### Message Queue settings card - Extend `useMessageQueueSettingsLoad` and `useMessageQueueSettingsDraft` in `apps/web/components/settings/system/message-queue-settings.tsx` with a third draft/baseline. Include it in contributor revision, dirty/valid/save/discard logic, and concurrency-safe response reconciliation. - Add a separate `AutoMergeToggleFields` presentation block below the existing manual merge block. Use the label **Automatically merge consecutive messages**, explanatory same-source/fallback copy, a stable test ID, and the existing admin/member and shared floating-save behavior. - Keep the current Task Behavior page, card width, single settings scroll owner, and one-column responsive layout. The switch and surrounding row must remain touch-safe and clear the mobile save bar. No queue-panel component changes. - Add all user-facing copy to `apps/web/src/locales/en/system.json`, regenerate the pseudo catalog, and run i18n checks and the changed-line ratchet. --- ## Tests - **What:** strict same-source compatibility, identity preservation, ordered content/context/attachment merge, metadata mismatch fallback, combined-limit fallback, and no half-write. **File:** new `apps/backend/internal/orchestrator/messagequeue/repository_auto_merge_test.go` plus env-gated Postgres cases. **How:** table-drive the same contract over memory, SQLite, and Postgres; compare complete pre/post snapshots on skipped and failing paths. - **What:** default-on service admission, disabled behavior, three-message chaining, cap-before-merge, concurrent admissions/drain, degraded repository error, and independence from manual merge. **File:** new `service_auto_merge_test.go` and focused updates to existing queue tests that intentionally need multiple compatible rows. **How:** RED service tests first, then race tests using the existing admission lock and repository hooks. - **What:** file-backed attachment claim succeeds before fold and claim failure removes only the new source. **File:** `queue_handlers_test.go` or a new `queue_handlers_auto_merge_test.go`. **How:** handler-to-real-memory-service tests with blocking/failing attachment claim fakes and byte-for-byte target assertions. - **What:** returned surviving IDs remain valid for normal peer queueing and parent interrupt dispatch, while different senders, clarification, workflow, lifecycle, plugin-source mismatch, append, coalesce, and restore do not conflate. **File:** focused cases in `internal/orchestrator`, `internal/mcp/handlers`, and `internal/backendapp` tests. **How:** integration tests through existing real service fixtures. - **What:** settings default/upgrade/persistence/partial PATCH/live apply and environment-lock independence, including retention of the environment's live capacity after an auto-only PATCH. **File:** `internal/system/queuesettings/queuesettings_test.go`, `internal/backendapp/message_queue_settings_test.go`, and `internal/system/system_routes_test.go`. **How:** store, service, HTTP, and startup wiring tests. - **What:** third draft loads, saves alone, discards, survives a concurrent response, remains editable under only a max environment lock, and is disabled for members. **File:** `message-queue-settings.test.tsx` and `settings-api.test.ts`. **How:** component tests with the existing save-provider harness and API mocks. --- ## E2E Tests - **Scenario:** default-on setting persists and can be switched off/on without changing capacity or manual merge. **File:** `apps/web/e2e/tests/system/message-queue-settings.spec.ts`. **What to verify:** GET default, auto-only PATCH body, shared save bar, reload, environment-cap lock independence, member read-only state, and full baseline restoration in `afterEach`. - **Scenario:** two compatible user messages become one when enabled and remain two when disabled. **File:** `apps/web/e2e/tests/chat/message-queue.spec.ts`. **What to verify:** busy agent, final queue count/content/order, no transient second row after the response, and setting restoration even on failure. - **Scenario:** mobile exposes the same touch-safe switch without overflow, nested scroll ownership, or save-bar overlap. **File:** `apps/web/e2e/tests/system/mobile-message-queue-settings.spec.ts`. **What to verify:** visible switch, minimum touch size, save/discard, and persisted value. - Existing management, manual merge, send-now, and reorder E2E scenarios that require multiple compatible rows explicitly disable auto merge for their setup and restore the prior install value during teardown. Update desktop and `mobile-*` specs together. --- ## Verification Results - Backend repository, admission, handler, MCP, settings, startup, and race suites passed, including memory, SQLite, and environment-gated Postgres contracts. - Frontend passed 34 focused component/API tests, typecheck, focused ESLint, pseudo-locale generation, `i18n:check`, and `i18n:ratchet`. - Desktop Chromium E2E passed 20 tests; mobile Chromium passed 4 tests; the focused attribution, steering, and sidebar-count audit passed 3 tests. - Public documentation tests passed 60 tests, the validator accepted 41 published pages, and `git diff --check` passed. - No blockers remain. Review remediation verification also passed the focused automatic-merge repository/service tests and the message-queue race suite after adding the context-file cap and shared admission serialization for queue mutations. --- ## Implementation Waves And Parallel Candidates ```text Wave 1: - [x] [task-01-auto-merge-repository](task-01-auto-merge-repository.md) Wave 2: - [x] [task-02-auto-merge-admission](task-02-auto-merge-admission.md) Wave 3: - [x] [task-03-auto-merge-settings](task-03-auto-merge-settings.md) Wave 4: - [x] [task-04-auto-merge-settings-ui](task-04-auto-merge-settings-ui.md) Wave 5: - [x] [task-05-auto-merge-e2e](task-05-auto-merge-e2e.md) Wave 6: - [x] [task-06-auto-merge-docs](task-06-auto-merge-docs.md) ``` The dependency chain is sequential in the primary conversation. No wave authorizes subagents; only a later explicit user request can do that. ## Environment prerequisite If `apps/node_modules` is absent, run `pnpm install --frozen-lockfile` from `apps/` before frontend or E2E checks. Do not change the lockfile. ## Risks and boundaries - Automatic admission must not call the manual setting gate or loosen manual merge provenance rules. - File attachment claim rollback is destructive to the just-inserted source ID; automatic fold must never run before that claim succeeds, and a later admission must never use the provisional source as its target. - A post-insert fold error cannot be returned as an admission failure because a caller retry would duplicate accepted content. - Existing tests frequently queue multiple compatible user rows. They must opt out explicitly when row count is part of the scenario, while product defaults stay on. - No schema migration, feature flag, environment variable, retroactive sweep, queue-panel toggle, or capacity bypass is planned.