fix(agent-org): converge plans, formal events, and final reports

[ShiboSheng]

Dependency and goal

Stack strictly after #995 and before #764. The Agent Org redesign rollout gate remains disabled by default until this correction, the later Group/projection work, and the required real-provider/performance gates pass.

This issue owns one formal-convergence correction: durable Plan, Task, TaskOutput, and formal Inbox facts must each be processed once and must converge to a durable, visible final report. It freezes three inseparable boundaries:

1. Immutable Plan revision + exact approval versus Task lifecycle.
2. Task-bound formal trigger materialization versus repeated Coordinator wake/watchdog notices.
3. Completion evidence + durable final summary versus heuristic or infinite Finalizing.

The normative contract is the local design document docs/architecture/agent-org-long-lived-team-session-design.md, especially invariants 50–55, §11.2, and §25.11B. Design remains the highest authority.

Evidence and root cause

The real-provider Team session Build Local Texas Holdem Game exposed the user-visible failure:

• Planner produced a plan, but its Task appeared under Cancelled and the plan was no longer visibly available after Coordinator said it had approved it.
• Coordinator repeatedly revisited Member work in a short interval; the user could not tell which Task/Plan/Output event was being processed versus reprocessed.
• At the end every Member and Coordinator was Idle, while Overview remained at Finalizing for a long time.
• The requested delivery report and the final result did not appear in the Coordinator history.

The Coordinator-authored Task cancellations and unsafe takeover are owned by #995. This issue owns the separate convergence defects that made Plan decisions, formal events, and the final report disappear, repeat, or remain unresolved.

Current code confirms that this is cross-layer, not a copy-only defect:

• Plan revisions and artifacts are durable, and approval can complete the planning Task atomically, but Run View reads only pending approval summaries. An Approved/Changes Requested/Superseded revision therefore has no stable Overview/history contract.
• Coordinator turns use a generic bounded unread Inbox drain, while TaskExecution has an exact Task-bound input query. Materialization/read receipts do not yet express one business trigger, one Coordinator Turn, and one exact resolution.
• Working Watchdog can synthesize a new Coordinator stall notice and wake. It does more than repair the missing doorbell for an already-committed formal trigger.
• project_run_phase returns Finalizing whenever there are Tasks and no pending/in-progress/corrupt rows. Completed, Failed, or Cancelled terminal mixes can therefore show Finalizing even though no final-summary attempt exists.
• There is no durable FinalSummaryReceipt tying completion evidence to one Provider attempt, one assistant EventStore row, a terminal failure, and a user-visible Retry.

State after merge

• Submitting a Plan creates an immutable PlanRevision. The Planning Task remains In Progress with an Awaiting approval activity.
• Approve atomically commits the exact revision decision, Planning Task Completed, a TaskOutput referencing that revision, Task history, dependency unblocking, and formal triggers. Request Changes keeps the Task open and wakes the exact Planner Task once.
• Pending and resolved Plan revisions remain visible in Planner history and Overview. Plan acknowledgement or approval can never implicitly cancel the Task.
• Every actionable Task/TaskOutput/Plan/formal Inbox fact has one stable FormalTriggerReceipt. A bounded event burst may share one Coordinator Turn, but each source retains its own identity and resolution.
• Working Watchdog only re-delivers an existing actionable trigger whose durable doorbell is missing. It cannot create a new reminder, business message, revision, approval, cancellation, reassignment, completion, or final summary.
• Finalizing is projected only while one FinalSummaryReceipt is Pending, Running, or Persisting. Success persists the assistant result in EventStore. Provider/persistence/timeout/restart-unknown failure becomes terminal, returns the Team to Idle, preserves evidence, and shows Final report failed — Retry.
• A final summary may explain certificate-backed outputs, but it cannot replace a requested report/document TaskOutput or manufacture missing delivery evidence.

Implementation steps and authoritative entry points

1. Plan revision and Task atomicity

• Keep PlanRevision immutable and bind it to exact run, Planning Task, Member, Session, source Turn, artifact/content digest, and revision id.
• Submit writes a Pending decision/activity only; it does not complete, fail, or cancel the Task.
• Approve uses one IMMEDIATE transaction for exact revision Approved, Planning Task Completed, TaskOutput referencing that revision, history, dependency unblocking, and downstream formal triggers.
• Request Changes writes exact revision feedback and one continuation for the same Task/owner. A replacement submission creates a new immutable revision; the old one remains readable.
• Coordinator, User, and Automatic approval policies share the same Task postconditions; only decision_by differs.
• Cancelled requires a separate authorized cancel intent and structured reason. Plan claim, acknowledgement, supersede, recovery, or UI projection cannot infer it.

2. Durable formal triggers and Task-bound materialization

• Define a stable key org_run_id + trigger_kind + trigger_id + trigger_revision for Task assignment/progress/blocker, TaskOutput, Plan request/decision, and completion-relevant formal Inbox facts.
• Persist FormalTriggerReceipt and the Wake/outbox in the same transaction as the business fact.
• Receipt records source identity, target Coordinator, claim/materialization/resolution state, bound Coordinator Turn, attempt, and exact Task/owner/Turn/Output/Plan references when applicable.
• Coordinator enqueue claims one bounded row/byte-capped batch and materializes each exact source as durable visible Turn input before Provider execution.
• Provider success resolves only rows materialized into that Turn. Unclaimed, unrendered, unrelated-Task, user-directed, and later-arriving rows remain pending.
• Crash/restart/response-loss resumes or replays the original receipt and Turn; it never mints a new trigger or duplicate transcript input.
• Events arriving during an active Coordinator Turn keep their own receipt and coalesce to at most one follow-up wake after the current Turn.
• Delete the formal semantics of generic Coordinator blanket drain/ack. Run View and page reads remain pure and never claim or resolve.

3. Missing-doorbell-only Watchdog

• Keep the App-level fixed 60-second, Working-only, LIMIT 100 / 250 ms cooperative scan required by the design.
• Its indexed query may select only an existing actionable trigger that has no valid queued/running/terminal-processing receipt or whose committed doorbell is provably missing.
• Repair reuses the original trigger and receipt. It does not insert a new Coordinator repair message, bump work_revision, reset a new retry episode, or call Provider for an already materialized/terminal revision.
• Watchdog cannot approve Plan, cancel/reassign Task, request completion, create final summary, or decide that a slow Member needs intervention.
• No missing doorbell means a bounded no-op: zero business-row mutation and zero Provider wake.

4. Durable final-summary lifecycle

• Completion certificate/outcome from fix(agent-org): prevent Coordinator takeover and false delivery #995 remains the delivery authority. Only after it commits may the final-summary owner create a receipt for the current activation generation, certificate, evidence digest, and attempt.
• Freeze states as pending -> running -> persisting -> persisted|failed, with at most one active attempt.
• Final-summary context is bounded and read-only: certificate outcome, Completed TaskOutputs, Artifact handles, Plan decisions, failure/cancel facts, and a requested report's own TaskOutput.
• The final-summary Turn has no graph/work tools and cannot modify workspace, create/complete Task, or fill missing evidence.
• Persist assistant output to authoritative EventStore first, save its event id, then terminalize the receipt and Turn.
• Provider error, user Stop, existing Turn hard timeout, EventStore append failure, or unrecoverable started/unknown restart writes a typed terminal failure. No automatic LLM retry timer is allowed.
• A pending receipt may recover the same Turn. If EventStore already has the stable row but the receipt is nonterminal, reconcile it without another Provider call.
• A real Retry button creates the next idempotent attempt against the same certificate/evidence digest. The Team is Idle between attempts and existing evidence stays visible.

5. Wire, UI, observation, and recovery

• Plan projection returns Pending and terminal revision history, exact decision, Planning Task/Turn/TaskOutput links, and Awaiting approval separately from Task status.
• Finalizing projection reads only FinalSummaryReceipt and returns attempt/status/timestamps/event id/typed error/canRetry. all_tasks_terminal, typing atoms, frontend timers, and Member Idle are not inputs.
• Overview shows Plan Pending/Approved/Changes Requested, one-time formal event activity, certificate-backed Delivered/Cancelled/Failed, Finalizing, and Final report failed — Retry as separate dimensions.
• The requested report/document appears through its own TaskOutput/Artifact. The Coordinator final report links or summarizes it; it does not replace it.
• Add no-content metrics for Plan revision/decision atomicity, trigger receipt/materialization/resolution, doorbell delivery/repair/suppression, summary attempt/status/EventStore ordering, failure/Retry, and Finalizing duration.

Scope boundaries

• fix(agent-org): prevent Coordinator takeover and false delivery #995 continues to own Coordinator tool restrictions, no-progress waiting, safe cancel/reassign handoff, and completion certificate validation.
• No new Task state. Awaiting approval and Finalizing are activity/projection states.
• No rewrite of ordinary SDE Plan mode.
• No GroupMention or MemberInbox UserDirectedWork source; feat(agent-org): [9/10] add multi-target Group ingress and linked Member Inbox #764 still owns those adapters.
• No second Coordinator/Member runtime, dispatcher, scheduler, or Provider lane.
• No dynamic Watchdog cadence, per-Team timer, periodic Provider wake, automatic final-summary retry, or blanket Inbox drain.
• No external-user schema migration unless preservation is explicitly requested; canonical DDL/reset remains the current rollout-gated strategy.
• No final summary acting as Task execution, report generation, TaskOutput, or delivery evidence.
• Transcript auto-scroll/typing layout and repeated PR8 Return projection remain separately owned UI defects.

Failure scenarios that must be rejected or remain blocked

• Plan approval/ack/restart changes the Planning Task to Cancelled without an explicit authorized cancel intent.
• Old/wrong revision or wrong Task/Turn is approved.
• Plan decision, Task Completed, TaskOutput, dependency unblocking, or downstream trigger commits only partially.
• Approved Plan disappears from history or loses its exact TaskOutput link.
• One trigger/revision produces multiple receipts, Coordinator Turns, transcript inputs, or business resolutions.
• Generic drain consumes another Task or a user-directed row, or page refresh mutates claim/read/resolution state.
• Watchdog creates a new reminder/message/revision/Provider episode for the same trigger or acts on Member duration alone.
• All-terminal Tasks produce Finalizing without an active FinalSummaryReceipt.
• Two final-summary attempts run concurrently.
• EventStore append fails but the receipt becomes Persisted.
• Persisted/Failed receipt leaves the UI in Finalizing, or Failed automatically retries Provider.
• Final summary upgrades missing TaskOutput/report evidence to Delivered.
• Ordinary SDE Send/Queue/Force Send/Stop/Resume/Plan mode/Compaction creates Agent Org trigger/summary receipt, query, timer, or listener.

Acceptance

Deterministic owning-boundary tests

• Plan submit/approve/request-changes/supersede/cancel matrix across Coordinator/User/Automatic policies, including exact Task/Output/revision atomicity, replay/conflict, dependency unlock, restart, and fault injection.
• Formal trigger unique/replay/conflict, bounded batch, exact materialization/resolution, later-row isolation, response loss, Turn crash, restart, concurrent event burst, and pure Run View matrices.
• Business fact + Wake/outbox transaction fault injection proves there is no committed fact without a recoverable exact trigger.
• Watchdog missing-doorbell-only repair, five repeated ticks, no-new-fact no-op, status/limit/time budget, and zero reminder/revision/Provider mutation.
• FinalSummaryReceipt full FSM, single-active attempt, evidence digest replay/conflict, Provider error, Stop, hard timeout, EventStore error, restart reconciliation, Retry, and EventStore-before-terminal ordering.
• Task terminal without summary receipt is not Finalizing; Persisted/Failed exits Finalizing and can reach Idle.
• Ordinary SDE has zero Agent Org context, receipt, query, listener, timer, or Plan behavior change.

Real provider and packaged Tauri

Use a fresh isolated Team and a real provider for one realistic user journey based on Build Local Texas Holdem Game:

1. The user asks the Team to plan, implement, run, and verify a functioning local Texas Hold'em game, and explicitly requests a durable implementation/test report as a formal deliverable.
2. Planner uses real Plan mode. Observe In Progress + Awaiting approval and open the visible Plan. Exercise Coordinator policy in the main run, plus the real user Plan approval buttons in a focused run; debug helpers do not approve.
3. After approval, verify the Planning Task is Completed, never Cancelled, and its exact approved Plan + TaskOutput remain visible in Planner history and Overview after Session switch, refresh, App quit, and restart.
4. Implementer and Tester produce real TaskOutputs. A burst of progress, Plan, and TaskOutput events starts at most one active Coordinator Turn; each exact event appears once.
5. Keep one Member deliberately slow. Across five Watchdog ticks, confirm no duplicate Coordinator transcript input, no reminder message, no repeated Provider wake, and no interruption based on elapsed time.
6. Verify the requested implementation/test report exists as its own TaskOutput/Artifact before delivery can be certified.
7. Confirm Finalizing appears only for the active FinalSummaryReceipt and the real final report appears in Coordinator history, linked to certificate evidence and the requested report.
8. In an isolated fault run, seed only Provider/EventStore failure prerequisites with a debug fixture. Use Computer Use to perform the visible Retry. Finalizing must exit to Idle with evidence preserved; five minutes of failure state produces zero automatic Provider/Wake.
9. Use Computer Use for every visible create/open Team, Send, Plan open/decision, Session switch, Stop, Retry, Pause, Resume, Archive, Delete, and confirmation action in the packaged Tauri App. Debug endpoints may seed isolated faults or read DB/log/receipt evidence only.
10. Record exact Plan/trigger/summary receipts, EventStore ids/order, Task/TaskOutput links, provider/runtime counts, Watchdog SQL/rows, screenshots, and Command+5 request evidence.

Real-provider unavailability, quota exhaustion, or rate limiting is Blocked, not Pass.

Performance and lifecycle gates

• Same formal trigger/revision remains exactly one receipt, one materialized input, and at most one active/terminal-processing Coordinator Turn after response loss, restart, Session switching, refresh, and five Watchdog ticks.
• No-new-trigger five-minute window has zero Coordinator Provider, observation query, shell/process, or business Inbox mutation. Only the bounded Watchdog scan is allowed.
• Watchdog remains fixed 60 seconds, Working-only, LIMIT 100, and 250 ms cooperative budget; no per-Team timer or dynamic cadence.
• Provider terminal/timeout to FinalSummaryReceipt terminal: P50 <= 1 second, P90 <= 5 seconds, hard wait <= 10 seconds.
• Persisted/Failed immediately removes Finalizing. Failed five-minute window has zero automatic Provider retry, Wake, timer, or growing retained state.
• Formal trigger and final-summary projections remain row/byte bounded with large Task/Inbox/Artifact history.
• Ordinary SDE request/timer/listener/query counts remain at baseline.

Effort

Category	P50	P90
Production	4,200 review lines	6,800 review lines
Tests / E2E / measurement	4,500	7,600
Old-path removal / locale / audit	800	1,600
Total	9,500	16,000
Substantive files	50–65	70–90
Additional locale files	up to 13	up to 13
Audit/evidence documents	2–4	3–5

At 70% of P50, recheck scope and actual diff. If the work requires a second dispatcher, a new Task state, an ordinary-SDE Plan-mode rewrite, external-user migration, more than three unplanned production files / 200 production lines, or total growth above 20%, stop and update the design and issue before implementation. Do not reduce atomicity, recovery, real-provider, packaged-app, SDE, or performance evidence to fit the estimate.

Plain-language contract

A Planner's plan is a real saved result, not a temporary chat thought. Approving it must complete the right Planning Task and keep the plan visible. When a Member reports progress or finishes work, the Coordinator should receive that fact once—not be repeatedly woken to ask again. When the work is over, Finalizing means the Team is actually writing one saved final report. That report either appears, or the UI says it failed and lets the user retry; it never spins forever or pretends a missing report was delivered.