Skip to content

feat(agent-org): add long-lived Team lifecycle and durable quiescence #702

Description

@ShiboSheng

Stack position

This is the foundation of an ordered five-PR stack. Later PRs must build on its schema, lifecycle, receipts, and generation fences; this issue must not expose the complete long-lived Team experience by itself.

Problem / Motivation

Agent Org currently treats a batch of work as a terminal Run. Startup, completion, Pause/Resume, recovery, Archive, polling, and deletion do not yet share one durable long-lived Team lifecycle. That makes it possible to observe half-started Teams, infer Team state from generic Session activity, or let late Worker and recovery signals cross a lifecycle boundary.

Goal

Create the trustworthy lifecycle foundation for one Conversation to own one long-lived Team. A finished batch moves from Working to Idle instead of killing the Team; startup and Pause/Resume are recoverable; Archive is a permanent fence; and Quiescence is derived from durable work-capable facts.

Required scope

  • Make Starting / Working / Paused / Idle / Failed / Archived the only authoritative Team states.
  • Update the canonical Agent Org DDL directly and validate it against fresh/reset Agent Org data. Remove legacy compatibility helpers only for the tables rewritten by this stack.
  • Persist activation_generation, Starting materialization intent/receipts, Archive receipts, and the lifecycle fields required by recovery.
  • Implement durable Pause/Resume receipts: Pause commits the Paused fence and generation bump before concurrently yielding Coordinator/TaskExecution turns; Resume advances authorization exactly once and reconnects work using stable original-turn identity.
  • Persist Agent Org Turn kind in canonical Turn Intent. This PR supports Coordinator and TaskExecution; MemberConversation remains disabled until PR 4.
  • Replace terminal-only Finality with one transactional Quiescence decision that checks open Tasks, work-capable Turns, EventStore finalization, materialization, and recovery reservations.
  • Commit Archive fence/generation before runtime teardown. Allow only the narrow internal archive cancellation path until PR 3 introduces complete Task terminal semantics.
  • Show minimal Idle/Archived state in Run View; stop fallback polling for Idle/Paused/Archived and destroy the interval when no Team is pollable.
  • Bound Watchdog scanning by state, batch size, and time budget.
  • Accept destructive Delete only for Archived and quiesced Teams; the complete dangerous-zone UI belongs to PR 5.

Locked invariants

  • Team status is not inferred from generic Session status or Provider runtime presence.
  • Working → Idle has exactly one transactional writer.
  • Starting recovery reuses the same canonical Root/member identities and receipts.
  • Pause, Resume, Archive, Wake, Recovery, and callbacks all honor durable generation/lease fences.
  • Archive is terminal: once its transaction commits, late work cannot recreate a runtime or mutate Team work state.
  • This schema is canonical for its commit; old binaries are not required to read the new schema.
  • Ordinary SDE Sessions do not read Agent Org lifecycle tables or inherit Agent Org polling.

Acceptance criteria

  • Fault injection at every Starting materialization write boundary recovers the same member identity without duplicates.
  • Missing Root EventStore finalization blocks Working → Idle even if the model turn appears complete.
  • Quiescence races with Task mutation, recovery reservation, and member materialization fail closed.
  • A generic active Session without a work-capable Agent Org Turn neither blocks nor triggers Team lifecycle transitions.
  • Duplicate Pause/Resume and restart after commit do not duplicate generations or continuations.
  • Old lease callbacks cannot clear a replacement runtime and safely kick the FIFO only after release.
  • Archive wins races with Wake, Recovery, terminal callbacks, and runtime teardown.
  • Teardown timeout uses bounded retry and leaves the Team Archived with durable diagnostics.
  • Delete is rejected unless the Team is Archived and runtime-quiesced.
  • Idle/Paused/Archived have no persistent fallback poll; no pollable Team means no interval.
  • Watchdog scans only Working Teams and stays within configured batch/time limits.
  • Existing ordinary SDE Session behavior remains unchanged.

Verification

  • Targeted Rust lifecycle, generation-race, Watchdog, Quiescence, Archive, Pause/Resume, and delete tests.
  • session-persistence schema/Turn Intent tests and a fresh-schema test.
  • TypeScript typecheck plus Idle/Archived Run View store tests.
  • Minimal production-path UI smoke for the new states and passive polling gate.
  • Restart/crash tests covering receipts, leases, and exactly-once continuation.
  • Architecture audit across lifecycle ownership, FSM, persistence, wire mapping, initialization parity, and recovery.
  • Performance-guard lifecycle matrix for polling, Watchdog scans, runtime teardown, and repeated open/close.

Out of scope

  • Idle Coordinator question handling and the unified send path (PR 2).
  • Coordinator Task activation, complete Failed/Cancelled Task semantics, and Task authority changes (PR 3).
  • Direct or Group @Member conversation (PR 4).
  • Complete Archive/Delete UI, all locales, full E2E, and final performance sign-off (PR 5).
  • Proposal, confirmation, multi-Run timeline, new Team/Task product states, or changes to ordinary SDE semantics.

Effort and budget

  • Label: Effort: High
  • P50 range: 2,600–3,100 review lines; planning point: 3,100
  • P90 cap: 4,000 review lines
  • Expected substantive files: 18–24
  • At 70% of the P50 planning point, review the diff and risks. Above 1.25× P50, explain new entry points/test surface; at 1.5×, stop and re-spike before expanding scope.
  • The estimate used upstream/develop@b053d6d59 only as an Impact Spike snapshot. Implementation starts from the then-current develop.

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions