run start: add --wait to block until the run finishes

[jordanenglish]

Description

run start returns as soon as the run is created, so automating a plan/apply means hand-rolling a poll loop against run status. This adds --wait, which blocks until the run reaches a terminal state and maps the outcome to an exit code, so run start is usable directly in scripts and CI.

Behavior

• Streams each status transition as it happens.
• Exit code: applied / planned_and_finished / planned_and_saved exit 0; errored, canceled, discarded, and mandatory policy failures (policy_soft_failed, policy_override) exit non-zero.
• A plan that finishes but needs a manual apply (auto-apply disabled) stops with a clear message instead of hanging, keyed off the run's actions.is-confirmable.
• --timeout bounds the wait. If it elapses, tfctl stops watching and exits non-zero, but the run keeps running in HCP Terraform (this is a watch budget, not a cancel); the run URL is surfaced so you can follow up.
• On completion the elapsed time and run URL are printed. The final summary reuses the same renderer as run status (diagnostics, policy failures, task results).

Example Output

Wait through an auto-apply run:

$ tfctl run start my-workspace --wait
✓ run-abc123 created; waiting for it to finish...
  ⋯ pending
  ⋯ planning
  ⋯ applying
  ⋯ applied
Run succeeded
✓ Completed in 16s. View the run at https://app.terraform.io/app/my-org/workspaces/my-workspace/runs/run-abc123

Plan-only, or a workspace without auto-apply, stops for a manual apply rather than hanging:

$ tfctl run start my-workspace --wait
✓ run-def456 created; waiting for it to finish...
  ⋯ planning
  ⋯ planned
Plan finished; a manual apply is required (auto-apply is off).
✓ Planned in 12s. Confirm the apply at https://app.terraform.io/app/my-org/workspaces/my-workspace/runs/run-def456

Timeout leaves the run running server-side and exits non-zero:

$ tfctl run start my-workspace --wait --timeout 2s
✓ run-ghi789 created; waiting for it to finish...
  ⋯ plan_queued
✗ Stopped waiting; the run may still be running in HCP Terraform:
  https://app.terraform.io/app/my-org/workspaces/my-workspace/runs/run-ghi789
ERROR: timed out after 2s waiting for run run-ghi789 (last status: plan_queued)

PR Checklist

• Run npx changie new or install changie to prepare a new changelog entry for the next set of release notes.
  • Added .changes/unreleased/ENHANCEMENTS-*.yaml (kind: ENHANCEMENTS).
• Ensure any command changes are sensitive to these global flags:
  • --json — Force machine readable output to stdout. Does not apply to stderr.
  • --markdown — Force markdown output to stdout. Does not apply to stderr.
  • --dry-run — Don't make any actual writes or other mutations. Describe what would have changed to stderr.
  • --quiet — Don't render output to stdout.
  • Progress transitions, the "created" line, and the completion (elapsed + URL) line all go to stderr. The final run summary is rendered through the shared run status Outputter, so it honors --json/--markdown/--quiet identically to run status. --wait is a no-op under --dry-run (dry-run returns before any run is created).
• Get the logging interface from the context and add debug logging for interesting conditions and nonfatal situations.
  • No new silent nonfatal paths: timeout, cancellation, and "run still running" are surfaced directly to the user on stderr rather than swallowed.
• Run make gen/screenshot if the root command output changes.
  • Not required: only run start gains flags; the root command output is unchanged.
• Add the Autocomplete field to positional arguments and flags to assist shell autocomplete.
  • N/A: --wait is boolean and --timeout takes a freeform duration; neither has an enumerable completion set (consistent with the sibling run start boolean/value flags).

PCI review checklist

• I have documented a clear reason for, and description of, the change I am making.

• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.

  • Reverting the PR fully removes the change; no additional revert steps or data migration.

• If applicable, I've documented the impact of any changes to security controls.

  • N/A: --wait only polls read-only run status with the existing token; no auth, permission, or other security-control surface is changed.