fix: sequence AgentBus roster replies

.project-docs/30-worklog/tasks/20260831-fix-agentbus-roster-replies-4c8e1a72.md

@@ -0,0 +1,60 @@
+# Task: Fix AgentBus roster reply lifecycle
+
+## Identity
+
+- Task ID: 20260831-fix-agentbus-roster-replies-4c8e1a72
+- Mode: Feature
+- Branch: main
+- Worktree: /Users/inmanx/Documents/lwltAPI
+- Base commit: 693aed54aa40ef5516784bc96d97ba8f5c154b77
+- Owner: codex
+- Status: Ready for integration
+
+## Scope
+
+- Replace the generic AgentBus acceptance text for an initial roster directive with the existing explicit `.xls/.xlsx` waiting prompt.
+- Replace the generic acceptance text for a structured roster attachment with an attachment-specific received/validation prompt.
+- Ensure one roster task completion produces one final AgentBus result even though the directive and attachment arrive as separate inbound frames.
+- Preserve direct-listener and durable-outbox behavior, add regressions, run all repository gates, and push the bounded fix on `main`.
+
+## Intent And Constraints
+
+- Keep roster routes Program-only and retain attachment correlation, validation, task state, idempotency, privacy, and ERP execution behavior.
+- The initial `awaiting_attachment` message is a nonterminal input request and must not later claim the ERP final result; the attachment message that resumes parsing owns that result.
+- Internal final-reply ownership metadata must remain server-only and never appear in an outbound AgentBus payload.
+- Do not deploy, restart services, mutate Kubernetes, access ERP, read secrets, retry the live task, or send an external message.
+
+## Outcome
+
+- Confirmed the duplicate success was caused by durable finalization selecting every delivered accepted row for the same task. The original roster directive and the later attachment frame therefore each received the same terminal result.
+- Added one shared AgentBus delivery contract for the generic acceptance, roster waiting prompt, roster attachment-received prompt, and a server-only final-reply-eligibility marker. The marker is removed before every outbound frame.
+- Initial roster directives now persist the explicit waiting prompt and are not eligible to own the later ERP result. Attachment messages persist the attachment-specific prompt and remain eligible for the final result.
+- Durable finalization now selects only the newest eligible accepted delivery for a task, preserving backward compatibility for older rows without the marker while preventing duplicate success results.
+- Direct listeners now wait until ingestion identifies the reply phase: initial roster instructions return after the waiting prompt, normalized attachments alone wait for the terminal task, and duplicate attachments return their bounded duplicate notice without re-running parsing.
+- A combined directive-plus-attachment frame records only the attachment-phase delivery instead of first persisting a misleading waiting prompt.
+- Updated the active AgentBus reply contract and control-plane operator documentation. No parser, workbook validation, task state, ERP execution, deployment, or live channel state changed.
+
+## Verification
+
+- Focused AgentBus and roster-intake tests: 25/25 passed.
+- `node --run check:repo`: 10/10 passed.
+- `node --run check`: passed.
+- `node --run test:control-plane`: 143/143 passed.
+- `node --run test:legacy`: 256/256 passed.
+- `node --run build`: passed.
+- `check_project_docs.py`: passed.
+- `check_doc_drift.py --task-id 20260831-fix-agentbus-roster-replies-4c8e1a72`: passed.
+- `git diff --check`: passed.
+
+## Follow-ups
+
+- Deploy/restart and verify the three visible messages against a real WeChat roster flow only under separate authorization.
+
+## Promotion Candidates
+
+- Target canonical AgentBus/data-flow memory during a later Integration task.
+- Proposal: roster AgentBus messaging is stage-specific; the waiting directive does not own the final ERP result, the attachment message does, and each task terminal result is emitted once to the newest eligible inbound frame.
+- Evidence: `control-plane/src/agentbus-delivery.ts`, `control-plane/src/task-service.ts`, `control-plane/src/agentbus.ts`, their focused 25/25 regression, and the user-supplied duplicate-success screenshot.
+- Future impact: future multi-frame task workflows should explicitly identify which inbound frame owns the terminal result instead of treating every accepted frame as finalizable.
+- Semantic conflicts: none; this implements the existing requirement that the first roster message return an attachment request and makes the one-result user experience explicit.
+- Human confirmation required: no for this bounded reply correction; deployment and live retry remain separately authorized.