feat(environments): change repositories through a build (SUPER-3017)

Draft
SA
16d ago
+196-17

Milestone 3 of plans/20261030-0017-environment-builds.md (#9104). Stacked on #9166.

What it does

  • environment.update gains an optional startBuild: 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 repositories build with the new list and returns the environment plus pendingBuildId. The environment's repositories and primary switch only when the build succeeds, through the same guarded activateGolden as every build. A failed build changes nothing.
    • On an environment with no snapshot, repositories are set directly as today, and startBuild then builds it.
  • 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 optional pendingBuildId (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/trpc typechecks; 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.