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.

[brandonc]

Thanks for the PR! I'm going to use your commits and implement the review feedback I've given here.

[brandonc]

Let's mention the valid units and parsing arrangement.

Suggested change

	Description: "With --wait, the maximum time to wait for the run to finish (e.g. 30m). Defaults to waiting indefinitely.",
	Description: "With --wait, the maximum time to wait for the run to finish. Defaults to waiting indefinitely. Examples include \"30s\", \"1.5h\" or \"2h45m\". Valid time units are \"s\", \"m\", \"h\".",

[brandonc]

We should use a context timeout instead of a loop condition so that the timeout is more strictly adhered to.

Suggested change

	_, outcome, err := pollRunUntilSettled(ctx, opts.APIClient, runID, io, opts.PollInterval, opts.Timeout)
	ctx, cancel := context.WithTimeoutCause(ctx, opts.Timeout, errors.New("--wait timeout exceeded"))
	defer cancel()
	_, outcome, err := pollRunUntilSettled(ctx, opts.APIClient, runID, io, opts.PollInterval, opts.Timeout)

[brandonc]

Can you promote this message to NewRunSummary/buildRunSummary? I think this could be valuable for any command that uses NewRunSummary.

NewRunSummary reads the Run and can use Actions.IsConfirmable to refine the message based on the status in buildRunSummary... and export the value so you can read it off summary as a caller.