feat(environments): change repositories through a build (SUPER-3017)
Milestone 3 of plans/20261030-0017-environment-builds.md (#9104). Stacked on #9166.
What it does
environment.updategains an optionalstartBuild: boolean.- Without it: nothing changes. A repository or primary change on an environment with a snapshot is still refused with
FORBIDDEN(repositoriesFrozen). Released clients branch on error codes, so the new behaviour is opt-in (.agents/skills/trpc-compat/SKILL.md, "Change an error code"). - With it: such a change starts a
repositoriesbuild with the new list and returns the environment pluspendingBuildId. The environment's repositories and primary switch only when the build succeeds, through the same guardedactivateGoldenas every build. A failed build changes nothing. - On an environment with no snapshot, repositories are set directly as today, and
startBuildthen builds it.
- Without it: nothing changes. A repository or primary change on an environment with a snapshot is still refused with
- How the build runs:
- A change that moves a checkout builds from the base image. That is a different primary, going between one and several repositories (a lone repository sits at the workspace root), or a name clash that adds the owner to a path.
- Otherwise the build forks the snapshot, clones added repositories and deletes removed repositories' checkouts.
update's output gains an optionalpendingBuildId(additive).
Verified
- Unit tests:
checkoutLayoutMoves: adding a repository beside others keeps the layout; a second repository, another primary, and a name clash each move it.removedCheckoutPaths.- The checkout script deleting removed checkouts first.
packages/trpctypechecks; environment and sandbox suites pass; Biome clean.
Not verified: a real repository-change build. It's part of the end-to-end run on the #9110 preview, still pending (see #9110).
Linear: SUPER-3017
Summary by cubic
environment.update gains an optional startBuild flag so repository or primary changes on an environment with a snapshot trigger a build instead of being refused. Without the flag, behavior is unchanged and the change is still refused with FORBIDDEN. With it, the environment's repositories only switch when the build succeeds, and the response includes the new pendingBuildId.
Builds that move a checkout layout (a different primary, going from one to several repositories, or a name clash that renames a checkout) build from an image; otherwise they fork the snapshot and delete the removed repositories' checkouts.