Add staged connection diagnosis for opaque dial failures

[rossnelson]

Related issues

Related to #224 and #851.

What changed?

TL;DR: This PR diagnoses opaque Temporal server dial failures in stages. Users see where a connection failed and get a concrete next step without changing the original command error.

After a dial fails, the CLI probes DNS, TCP, and TLS. These probes use the remaining command context with a separate three-second cap. TEMPORAL_CLI_DISABLE_CONNECT_DIAGNOSIS disables them.

The diagnostic error carries allowlisted semantic facts instead of raw arguments or construction-time color state. It preserves native errors through unwrapping.

A single parent terminal boundary builds controlled reports and exact-redacts secret values known to the runtime. It performs one checked stderr write. Existing stdout, exit-status, and extension ownership remain intact.

Suggested commands use long flags with POSIX or PowerShell-safe quoting. Standalone Activity NotFound handling provides a second validation slice.

This PR is a reference transition slice, not the completed project standard. The structured error handling guide separates the durable direction from compatibility mechanisms retained on this branch.

Durable practices demonstrated here:

• Native wrapped errors and semantic domain facts
• Explicit terminal rendering with separate command, presentation, and status outcomes
• Typed token actions and bounded, cancelable family-specific diagnosis
• Conservative fallback when typed evidence is unavailable

Compatibility mechanisms that future families must not copy:

• The generated synchronous Fail recorder
• Duplicate config and secret resolution for display provenance
• Process-global color.NoColor mutation and single-flight Execute
• Shallow exact-value redaction and family-owned report conversion

Broader family adoption remains blocked on gates A-C in the guide. Declaring this the project standard remains blocked on gates D-E. The scope stays internal and does not add a JSON error schema, public status taxonomy, public cliext provenance, or provider interface.

Checklist

Stability

• Breaking changes are marked with 💥 in the PR title and release notes
• Changes to JSON output (-o json / -o jsonl) are treated as breaking changes

Design

• This feature does not depend on Cloud-only APIs or behavior (it works against an OSS server)
• New commands follow temporal <noun> <verb> structure (e.g. temporal workflow start)
• New flags are named after the API concept, not the implementation mechanism (good: --search-attribute, bad: --index-field)
• New flags don't duplicate an existing flag that serves the same purpose
• New flags do not have short aliases without strong justification
• Experimental features are marked with (Experimental) in commands.yaml

Help text (see style guide at the top of commands.yaml)

• All flags shown in help text and examples are implemented and functional
• Summaries use sentence case and have no trailing period
• Long descriptions end with a period and include at least one example invocation
• Examples use long flags (--namespace, not -n), one flag per line
• Placeholder values use YourXxx form (YourWorkflowId, YourNamespace)

Behavior

• Results go to stdout; errors and warnings go to stderr
• Error messages are lowercase with no trailing punctuation

Tests

• Added functional test(s) (SharedServerSuite)
• Added unit test(s) (func TestXxx) where applicable

Manual tests

Setup

No manual setup was used.

Happy path

Not rerun manually. Fresh automated verification passed:

go test ./... -count=1 -timeout=10m

The root command does not enter the nested cliext module.

Error case

Not rerun manually. The race suite exposes the documented concurrent color.NoColor race:

go test -race ./internal/temporalcli -count=1 -timeout=10m

This suite is expected to remain red until Phase C makes color command-local. It becomes a required green gate in Phase C.

The standalone cliext compile mismatch predates this branch. Until fixed, (cd cliext && go test ./...) must match the recorded baseline exception and must not be reported as green.

Composition

Not rerun manually.

What to look at first

• The connection and Activity paths are validation slices for the user experience, not a completed general framework.
• The terminal boundary separates original command errors from presentation failures while preserving output and status ownership.
• The probe policy runs only after a failed dial, shares command cancellation, has a three-second cap, and has a kill switch.
• The report boundary admits semantic facts, exact-redacts registered secrets, and renders typed suggestions for the active shell.
• The guide records the compatibility mechanisms and adoption gates that remain before broader rollout.

[CLAassistant]

All committers have signed the CLA.