When a workspace is created, it runs through multiple transitions:

• stop (start_count=0 to create persistent resources)
• start (start_count=1 to create ephemeral resources)

We're currently orchestrating these multiple transitions using a stateful client (CLI/UI).

The same is true of a workspace "restart" - there's norestart transition, only the orchestration of a sequence of state transitions.

What I'm proposing in this ticket is to produce a POC (and possibly an RFC if there's time) for a new API to initiate and track these multi-state workspace transitions. The control would move tocoderd, and bring uniformity to these transition sequences (i.e. we won't have to define them in both the CLI and the UI, like we currently do, leading to inconsistency).

This presents some challenges around multi-replica setups (locking), how we handle failures, etc - and these should be explored in the POC/RFC.

Ultimately the new API should expose simple endpoints like/workspaces/create and/workspaces/restart, and offer a streaming response to return the build logs and the progress through the sequence of steps. Maybe even a progress indicator likestep 1 of 4?

Moving forward, we could leverage this higher level of abstraction to define and coordinate more complex workspace operations such as transfers, snapshots, prebuild reassignments, etc.

The original need for this functionality:

We have to provision prebuilds in a stopped state - which means all of the persistent resources have been created but not the ephemeral ones; knowing how long the ephemeral resources take to provision will help us determine if prebuilds will actually be fast enough for user satisfaction.

We require full visibility into the series of transitions a workspace goes through to capture itstrue startup time.