Add upgrade apply for the CLI and API

[JAORMX]

Summary

With the Applier in place (PR #5410), expose it to users so they can apply an upgrade while preserving configuration, instead of manually re-running a workload with a new image. Part of RFC THV-0068, local scope.

• Add thv upgrade apply <name>: runs the check, shows the candidate image, new env vars, and any permission/transport/network posture drift, then prompts for confirmation. --dry-run reports the plan without applying; --env/--secret supply values for newly required variables; --yes (or a non-interactive shell) skips the prompt and fails loudly on missing required values; --image-verification mirrors thv run.
• Add POST /api/v1beta/workloads/{name}/upgrade, delegating to the same Applier so all clients share one apply path. The API path is always non-interactive (detached validator) and sources image verification from server config; the request body can only supply env/secret values — it cannot redirect the image or weaken verification. Apply failures return a sanitized 422 with the detailed cause logged server-side, so secret references in an error chain are never echoed to the caller.

Type of change

• New feature

Test plan

• Unit tests (task test) — API: happy path, no-op, 404/400, no-secret-leak (asserts a secret reference in the request never appears in success or 422 responses), route ordering. CLI: output-formatting helper.
• Linting (task lint-fix)

Changes

File	Change
cmd/thv/app/upgrade.go	apply subcommand + flags + confirmation
pkg/api/v1/workloads_upgrade.go	POST .../upgrade handler
pkg/api/v1/workloads.go, workload_types.go	Route + request type
docs/cli/*, docs/server/*	Regenerated reference

Does this introduce a user-facing change?

Yes — thv upgrade apply and POST /api/v1beta/workloads/{name}/upgrade. The command stops and replaces the existing workload (verifying and pulling the candidate image first); there is no automatic rollback, which the help text states.

Large PR Justification

This PR is ~1,007 lines, but only 330 are hand-written source; the remainder is generated reference and tests:

• 374 lines are auto-generated OpenAPI (docs/server/*) and CLI reference (docs/cli/*), produced by task docs. They must be regenerated and committed together (CI verifies them) and cannot be split.
• 303 lines are tests for the new handler and CLI helper.
• The 330 source lines are the CLI apply subcommand and the API POST handler — two thin callers of the same Applier that the user explicitly chose to ship together so all clients share one apply path. Splitting CLI from API here would duplicate the wiring and the "all clients benefit" goal of the RFC, and both are well under the threshold individually.

Special notes for reviewers

PR 5 of 6 in the RFC THV-0068 stack; based on #5410. The API path hardcodes the detached env-var validator and sources the verify mode from server config — a client cannot weaken verification or redirect the image via the request body.

🤖 Generated with Claude Code

[github-actions]

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

---

This review will be automatically dismissed once you add the justification section.

[codecov]

Codecov Report

❌ Patch coverage is 55.00000% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.88%. Comparing base (a87510f) to head (9a11b14).

Files with missing lines	Patch %	Lines
pkg/api/v1/workloads.go	0.00%	9 Missing ⚠️
pkg/api/v1/workloads_upgrade.go	70.96%	6 Missing and 3 partials ⚠️

Additional details and impacted files

@@                  Coverage Diff                  @@
##           upgrade-4-applier    #5411      +/-   ##
=====================================================
+ Coverage              68.83%   68.88%   +0.04%     
=====================================================
  Files                    634      634              
  Lines                  64301    64341      +40     
=====================================================
+ Hits                   44263    44319      +56     
+ Misses                 16758    16742      -16     
  Partials                3280     3280              

☔ View full report in Codecov by Sentry.
📢 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.

Large PR justification has been provided. Thank you!

[github-actions]

✅ Large PR justification has been provided. The size review has been dismissed and this PR can now proceed with normal review.

[jhrozek]

This maps every Apply error to 422, but the "the running workload is untouched on any of these" comment only holds for the preparation phase. Once Apply reaches the destructive recreate, two of its error paths fire after the workload has already been torn down:

• UpdateWorkload failing (stop/delete already initiated)
• completion() failing (old workload deleted, replacement didn't start)

In those cases a 422 is misleading: it tells the client the request couldn't be processed and nothing changed, when the workload may actually be gone and not running. A client seeing 422 will reasonably assume it's safe to retry against an intact workload, when it's really a 5xx-class state.

Could we distinguish the two? A typed/sentinel error out of Apply (e.g. preparation vs recreate) lets the handler return 422 for prep failures and 500 for recreate failures. At minimum it'd be worth fixing the comment so it doesn't claim "untouched" for the post-UpdateWorkload paths.