Split the SSH extension telemetry category by failure outcome

[anton-107]

Changes

CheckIDESSHExtension reported four distinct outcomes as one telemetry category,
IDE_SSH_EXTENSION_MISSING. Split it into four, each attributed through an
errors.Is sentinel rather than message matching:

Outcome	Category
--list-extensions failed, so what is installed is unknown	IDE_SSH_EXTENSION_LIST_FAILED
Missing or too old, install attempted, IDE rejected it	IDE_SSH_EXTENSION_INSTALL_FAILED
User was asked and declined	IDE_SSH_EXTENSION_INSTALL_DECLINED
Consent could not be obtained (no --auto-approve, no usable prompt)	IDE_SSH_EXTENSION_INSTALL_UNAVAILABLE

IDE_SSH_EXTENSION_MISSING is retired rather than reused, and the enum comment
says so: rows written before this change still carry it, so a query spanning the
release has to accept both spellings.

A Ctrl-C is no longer counted as a failed install

Splitting the category exposed that it was collecting users who simply gave up.
exec.CommandContext kills the child and returns *exec.ExitError, which does
not wrap context.Canceled, so category()'s existing USER_ABORTED branch
never fired for a step that shells out: an interrupted extension check was
reported as a rejected install or a failed list.

Run now records the connect context's error alongside the returned error, and a
cancellation wins over the category recorded at the failure site. The telemetry
defer is registered after defer cancel() and so runs before it (LIFO), which
means the context is cancelled there only by the signal handler or the caller,
never by Run's own cleanup.

It matches the cancellation cause rather than testing for any context error, so
an expired deadline would stay a timeout instead of becoming a user abort. No
ancestor of the connect context carries a deadline today — there is no
WithTimeout/WithDeadline on the command path and Run never reassigns ctx
after its own WithCancel — so that case is currently unreachable, but the
predicate should not assert something false, and storing the cause keeps the
discrimination in category() where it is unit-testable.

This matters most where the split is meant to pay off: INSTALL_FAILED is one of
only two categories reachable under --auto-approve, which the VS Code
extension's tunnel button always passes, so abandoned attempts were landing
directly in the bucket that is supposed to mean "the marketplace or a policy
blocked the install".

Error messages

The two exec failures now lead with their sentinel, so their wording changes. The
two consent messages are unchanged from before the split: prefixing those with
%w made the most common path lead with a CLI-internal tag and then restate the
problem. They use a consentError that renders the message and unwraps to the
sentinel, the same shape as bundle/configsync's noMatchingSelectorError. No
acceptance golden depends on any of this text.

Why

This category is the largest single source of failed IDE-mode tunnels, and the
stickiest: of the users whose first attempt hit it, only about an eighth ever
established a tunnel, despite averaging 2.7 attempts. It is also the category we
can say least about, because the four outcomes need different fixes — a list
failure means the check never ran, while a rejected install points at the
marketplace or a policy forbidding it. One value cannot tell us which to fix, so
this is a prerequisite for fixing the dominant failure rather than a fix itself.

Only LIST_FAILED and INSTALL_FAILED are reachable under --auto-approve, so
the split also separates IDE-button traffic from direct CLI use, which the single
category could not.

Tests

Unit:

• TestSshExtensionErrorCategory pins the sentinel-to-category mapping, including
  through wrapping, and that an unsentinelled error falls back to UNKNOWN.
• TestCheckIDESSHExtension_ListFails covers a command that resolves on PATH but
  whose --list-extensions exits non-zero — the case that must not read as an
  install problem.
• TestCheckIDESSHExtension_AutoApprove_InstallFails covers a rejected
  --install-extension, the one outcome the IDE button can produce here.
• TestCheckIDESSHExtension_Declined drives the real prompt and answers "n", so
  the declined path is covered end to end rather than against a hand-built error.
  Verified by mutation: returning the Unavailable sentinel from that branch is
  not caught without this test, and is caught with it.
• TestConnectOutcomeCategory gains cases for a cancellation winning over the
  category recorded at the failure site, for an expired deadline staying a
  timeout, and for an interruption after the tunnel is up reporting no category.
• The consent tests assert the full message, so a sentinel cannot leak back into
  the text the user reads.

End to end, against real workspaces, reading the telemetry the CLI actually
uploads:

• Same interrupted extension check, built before and after the fix: identical
  error text (could not list installed extensions in VS Code: signal: killed),
  IDE_SSH_EXTENSION_LIST_FAILED before and USER_ABORTED after.
• An uninterrupted failing --list-extensions still reports
  IDE_SSH_EXTENSION_LIST_FAILED, and ingestion accepts it (see Merge order).
• A real serverless tunnel with a remote command: Connected!, remote output
  received, is_success: true, error_category: TYPE_UNSPECIFIED,
  server_start_time_ms: 29556, exit code 0. This covers the parent process; the
  ssh connect --proxy child logs its own event, and ToProxyCommand does not
  propagate --log-level, so that one was not observed directly.

go build ./..., go vet, the full ./experimental/ssh/... and
./libs/telemetry/... suites, TestAccept/ssh, and ./task lint-q are clean.

Not in scope

CheckIDESSHExtension reads --list-extensions with exec.Cmd.Output(), which
waits for the stdout pipe to close. If the IDE command forks, killing it on
cancellation leaves the grandchild holding the pipe and the call blocks past the
Ctrl-C. Pre-existing and unrelated to the categories; noted here because it
surfaced while testing the interrupt path.

No changelog fragment: this is internal telemetry under experimental/, matching
#4881, #6058 and #6321.

This pull request and its description were written by Isaac.

[anton-107]

Review

The refactor is sound and well-executed — sentinel-based attribution instead of string matching, retiring rather than reusing the enum value, a documented migration note, and clean removal with no dangling references to the old constant. CI is fully green, and I independently confirmed lint/vet clean and all four suites passing. The acceptance-golden claim holds (grepped; nothing depends on the old text).

Three things worth fixing before merge, in severity order.

---

1. Ctrl-C during install is silently counted as INSTALL_FAILED — and the new comment asserts the opposite

Probed directly (fake IDE that hangs on --install-extension, cancelled mid-flight):

err: could not install the Remote SSH extension in VS Code: signal: killed
errors.Is(err, context.Canceled)             = false   <- category() checks this for USER_ABORTED
errors.Is(err, ErrSSHExtensionInstallFailed) = true

exec.CommandContext kills the child and returns *exec.ExitError; it does not wrap context.Canceled. So category()'s USER_ABORTED branch never fires, and the attempt lands in IDE_SSH_EXTENSION_INSTALL_FAILED. Same applies to LIST_FAILED.

The misattribution itself predates this PR — it previously fell into the undifferentiated MISSING bucket, where it was harmless. What's new is the claim this PR bakes into ssh_tunnel.go:

Points at the marketplace or a policy that forbids the install rather than at anything the user chose.

For a user who Ctrl-C's a slow marketplace download, that is precisely backwards. This matters more than it looks: under --auto-approve — which the IDE button always passes — INSTALL_FAILED is one of only two reachable categories, so this pollution lands directly in the bucket the PR says will be used to diagnose marketplace/policy blocks.

One viable fix: check ctx.Err() in Run's telemetry defer and let it win over the site category. The defer ordering already works in your favour — defer cancel() is registered first, so the logging defer runs before it (LIFO), meaning ctx.Err() there reflects genuine cancellation rather than the function's own cleanup. Alternatively, propagate ctx.Err() at the two exec sites in run.go. Either way, if you'd rather not fix it now, the comment should say so rather than claim the opposite.

2. The DECLINED mapping has no real coverage — proven by mutation

Changing the declined branch to return the wrong sentinel (Unavailable instead of Declined) and running the full vscode + client suites:

ok  github.com/databricks/cli/experimental/ssh/internal/vscode  2.887s
ok  github.com/databricks/cli/experimental/ssh/internal/client  (cached)

Both green. Nothing tests that CheckIDESSHExtension actually returns ErrSSHExtensionInstallDeclined on the declined path. TestSshExtensionErrorCategory hand-constructs the sentinel (fmt.Errorf("%w: install it with ...", vscode.ErrSSHExtensionInstallDeclined)), so it verifies the switch statement against itself — tautological for the wiring. The other three new sentinels are covered end to end; DECLINED is the gap, and it is the one that distinguishes "user said no" from "couldn't ask," which is the distinction the analysis rests on.

This is easily closed. The following passes and does catch the mutation:

ctx, tst := cmdio.SetupTest(t.Context(), cmdio.TestOptions{PromptSupported: true})
defer tst.Done()
go func() { _, _ = io.Copy(io.Discard, tst.Stderr) }()   // prompt goes to stderr; must be drained or it deadlocks
go func() { tst.Stdin.WriteString("n\n"); tst.Stdin.Flush() }()
err := CheckIDESSHExtension(ctx, VSCodeOption, false)
assert.ErrorIs(t, err, ErrSSHExtensionInstallDeclined)

Same pattern as settings_test.go:531. (The AskYesOrNo-error → Unavailable path is also untested, but that one is harder to reach and lower value.)

3. The merge-order safety claim does not hold as written

The description says: "unknown enum values are ignored, so this PR is safe to merge in either order — it just is not queryable until both are in." Testing protojson against a plain (non-well-known) enum:

unknown enum VALUE                  -> err = proto: invalid value for enum field type: "TYPE_TOTALLY_UNKNOWN"
unknown enum VALUE + DiscardUnknown -> err = <nil>,  field = <zero value>

By default an unknown enum value is a hard unmarshal error. It is only tolerated with DiscardUnknown: true — and DiscardUnknown is documented for unknown fields, so relying on it for unknown values is a second assumption. Which branch applies depends on the ingestion pipeline's options, which isn't visible from this repo. Both outcomes are worse than "not queryable":

• No DiscardUnknown → the whole SshTunnelEvent row fails to parse. That loses the entire event for every IDE extension failure, not just the category — strictly worse than today.
• With DiscardUnknown → the field collapses to its zero value, TYPE_UNSPECIFIED, which is exactly what the CLI sends on success. Failures would read as successes on that field. (is_success = false still saves you for post-v1.14.0 rows, but error_category becomes actively misleading for the window.)

Worth confirming with whoever owns ingestion before merging ahead of the proto PR. Also worth linking the companion universe PR in the body — it is referenced but not linked.

---

Minor

The sentinel does double duty as machine tag and user-facing prose, and on the most common path it reads backwards:

Error: cannot prompt to install the Remote SSH extension: Required extension
"Remote - SSH" is not installed in VS Code. Install it with: code --install-extension ...

It leads with a CLI-internal mechanism and then redundantly restates the install. The prior wording opened with the user's actual problem. Since the description says the messages were hand-checked and "read correctly," this one is worth a second look — consider a terser sentinel, or keep the sentinels purely for errors.Is and lead the message with the problem.

Nothing else: error strings are ST1005-clean, the --auto-approve reachability claim checks out (only LIST_FAILED/INSTALL_FAILED), and skipping the changelog fragment matches the cited precedent.

_{Review performed by Isaac.}

[eng-dev-ecosystem-bot]

Integration test report

Commit: 0c498db

Run: 33879342911

	Env	✅​pass	🙈​skip	Time
✅​	aws linux	276	15	6:23
✅​	aws windows	278	13	4:09
✅​	azure linux	275	15	6:42
✅​	azure windows	277	13	4:27
✅​	gcp linux	276	15	7:11
✅​	gcp windows	278	13	5:01

Top 6 slowest tests (at least 2 minutes):

duration	env	testname
4:23	gcp windows	TestAccept
4:22	azure windows	TestAccept
4:07	aws windows	TestAccept
3:57	gcp linux	TestAccept
3:56	azure linux	TestAccept
3:56	aws linux	TestAccept