feat: pause auto-promotion after rollback

[jacobboykin]

Relates to #3016

Summary

This PR teaches Kargo to remember when someone intentionally rolls a Stage back while auto-promotion is enabled.

Without this, a rollback can look like it worked and then the Stage controller can immediately auto-promote the Stage back to the newest candidate. That is technically consistent with auto-promotion, but it is surprising UX. The key change here is that a user-directed Promotion directly to a Stage, selecting Freight other than the current auto-promotion candidate, creates an auto-promotion hold for that Freight origin, and auto-promotion stays paused for that origin until someone promotes the current candidate or resumes it.

This PR is specifically about the auto-promotion-hold side of rollback behavior. It gives the UI a concrete way to show "auto-promotion is paused because this looked like a rollback".

Mental Model

There are two hold states:

• Pending: the API has detected rollback intent and created a hold before creating the Promotion, but the Promotion has not succeeded yet. This is deliberately temporary. If the Promotion fails, errors, is aborted, or never gets created, the hold is removed.
• Active: the rollback Promotion succeeded, so the hold is now preserving that rollback. Active holds block auto-promotion for only that origin. Other origins requested by the Stage can keep moving.

Resume only clears an active hold and refreshes the Stage. It does not force a Promotion. The normal Stage reconciler still decides whether there is a valid auto-promotion to create.

How It Works

• The promote API looks up the current auto-promotion candidate for the selected Freight origin.
• If the user selected Freight other than the current auto-promotion candidate, it writes a Pending entry to stage.status.autoPromotionHolds[origin] before creating the non-auto Promotion.
• The pending hold records the selected Freight, origin, actor/reason, Promotion name, and eventually the Promotion UID.
• The Stage controller watches the linked Promotion:
  • success turns the hold Active
  • failure/error/abort removes the hold
  • a missing Promotion is tolerated briefly, then the hold is abandoned
• The auto-promotion path checks live Stage status before creating auto Promotions. Holds block newer auto Promotions for that origin, and pending auto Promotions that lose the race to a hold are aborted with a clear message.
• If the user promotes the current candidate while a hold is active, the API annotates that Promotion. When it succeeds, the controller clears that exact hold.

The exact-hold matching is intentional. Activate and clear paths compare the live hold against the observed hold identity before mutating status, including Freight, origin, Promotion name/UID, and created timestamp. That keeps stale caches or older Promotions from clearing newer rollback intent.

UI and UX

• The Promote drawer warns before promoting Freight other than the current auto-promotion candidate.
• For rollback Promotions, the optional reason field is placed in the drawer footer directly above the Roll back and pause auto-promotion action.
• DAG Freight tiles show passive Pause pending / Auto-paused tags for the selected origin. These are status labels only
• DAG Stage nodes show an auto-promotion-hold icon button in the node header when any origin is held.
• List view shows a Resume action button next to Promote when the Stage has holds.
• The DAG header button and list Resume button open the same holds popover.
• Each origin row links to the held Freight and the current auto-promotion candidate
• Active rows expose a per-origin Resume action. Pending rows are disabled until the rollback Promotion settles.

The multi-origin behavior is intentionally origin-scoped: resuming one origin does not resume the others.

API/CLI

This adds REST support for:

• GET /v1beta1/projects/{project}/stages/{stage}/auto-promotion/candidates
• POST /v1beta1/projects/{project}/stages/{stage}/auto-promotion/resume

It also adds kargo resume-auto-promotion --stage ... --origin Warehouse/name.

[netlify]

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	0b79858
🔍 Latest deploy log	https://app.netlify.com/projects/docs-kargo-io/deploys/6a2acc0efbf660000855802a
😎 Deploy Preview	https://deploy-preview-6334.docs.kargo.io
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[codecov]

Codecov Report

❌ Patch coverage is 73.63265% with 323 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.00%. Comparing base (8296b8e) to head (0b79858).

Files with missing lines	Patch %	Lines
pkg/controller/stages/regular_stages.go	70.56%	64 Missing and 24 partials ⚠️
pkg/controller/promotions/promotions.go	61.25%	49 Missing and 25 partials ⚠️
...i/cmd/resumeautopromotion/resume_auto_promotion.go	20.77%	61 Missing ⚠️
pkg/server/promote_to_stage_v1alpha1.go	83.51%	21 Missing and 9 partials ⚠️
pkg/server/auto_promotion_v1alpha1.go	79.57%	19 Missing and 10 partials ⚠️
pkg/api/auto_promotion.go	91.62%	14 Missing and 5 partials ⚠️
pkg/cli/cmd/promote/promote.go	37.50%	10 Missing ⚠️
api/v1alpha1/request.go	0.00%	7 Missing ⚠️
pkg/cli/client/error.go	77.77%	1 Missing and 1 partial ⚠️
pkg/server/rest_router.go	87.50%	2 Missing ⚠️
... and 1 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6334      +/-   ##
==========================================
+ Coverage   58.47%   59.00%   +0.52%     
==========================================
  Files         501      505       +4     
  Lines       42141    43139     +998     
==========================================
+ Hits        24642    25454     +812     
- Misses      16011    16131     +120     
- Partials     1488     1554      +66     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jacobboykin]

This is the intended method for kargo EE to consume. For example:

 promo, err := kargo.NewPromotionBuilder(c).Build(ctx, *stage, rollbackFreight.Name)
 if err != nil {
     return fmt.Errorf("error building rollback Promotion: %w", err)
 }

 if err = api.CreatePendingAutoPromotionHold(
     ctx,
     c, // client used for Stage status writes (and Promotion create, unless overridden)
     client.ObjectKeyFromObject(stage),
     promo,
     *rollbackFreight,
     api.AutoPromotionHoldOptions{
         Actor:  api.FormatEventControllerActor(controllerName),
         Reason: "Rollback to last known-good Freight",
     },
 ); err != nil {
     if exists, ok := errors.AsType[*api.AutoPromotionHoldExistsError](err); ok {