Emit structured local runtime errors

[sdairs]

Summary

• emit a stable redacted error envelope on stderr for local JSON and coding-agent runtime failures
• defer first-run telemetry notices and suppress telemetry-debug output when a structured error owns stderr
• add typed local codes for server state, versions, ports, startup, downloads, I/O, and bounded fallback errors
• preserve human, clap, Cloud, telemetry privacy, exit-code, and child-process behavior
• document the schema and stability contract

Tests

• cargo test -p clickhousectl -- --test-threads=1
• cargo test -p clickhousectl --test local_structured_errors_test -- --test-threads=1
• cargo test -p clickhousectl --test telemetry_test -- --test-threads=1
• cargo clippy -p clickhousectl --all-targets -- -D warnings
• cargo fmt --all --check
• cargo check -p clickhousectl --no-default-features

Closes #475

[sdairs]

Carry-over review from PR #510 (old PR for #475). This PR's error model is better than #510's (typed engine-agnostic variants like PortInUse { kind, port } / StartupExit / StartupTimeout eliminate #510's mislabel and duplicate-variant Bugbot rounds; private DTO surface; honest optional command; rollback errors recurse into primary so the real code survives; and it fixes the one finding left unanswered on #510 — port exhaustion now maps to port_in_use for both engines). But it regresses the single-JSON-on-stderr guarantee that #510 explicitly fixed. Required:

1. BLOCKER — first-run telemetry notice and telemetry-debug JSON corrupt the one-JSON-on-stderr contract (empirically verified on this branch). Emit structured local runtime errors in JSON mode #510 spent two fix commits on this; sdairs confirmed:

   • "Fixed in a198463. Structured local failures now defer a missing first-run telemetry notice without writing the consent marker, so stderr remains one JSON value."
   • "Fixed in 39633ed… finalize_inner now suppresses only Action::Debug when a structured local error defers telemetry output… asserts stderr is exactly one JSON value."
     This PR touches no telemetry code (main.rs returns no defer flag; finalize_inner has no suppression). Verified with a fresh $HOME and the built binary: (a) first-ever run of a failing local --json command prints the JSON error object followed by the first-run telemetry notice — two documents; (b) CHCTL_TELEMETRY_DEBUG=1 on a failing run emits two JSON documents (error envelope + telemetry payload). The README claim "writes exactly one error object to stderr" is therefore false on first run and in telemetry-debug mode — precisely the fresh-agent-install scenario the issue targets. The existing test suite cannot see this: every subprocess helper does .env_clear() + DO_NOT_TRACK=1, bypassing telemetry entirely. Port Emit structured local runtime errors in JSON mode #510's defer_telemetry_notice handling and add a fresh-home, no-DO_NOT_TRACK subprocess test asserting stderr is exactly one JSON value (as Emit structured local runtime errors in JSON mode #510 had).

2. Minor (decision, documented so probably fine): error.command became optional (skip_serializing_if) where the issue's example envelope always included it; ensure consumers keying on it handle absence.

CI note: postgres edge-cases failures are pre-existing on the stack base (from #547's script drift), not this PR.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c79bf76. Configure here.}

[cursor]

JSON install skips running-server check

Medium Severity

When structured_output is set, the commit callback always returns Ok(false) instead of calling version_in_use_by_running_server. JSON/agent master reinstalls then skip metadata recovery and can commit even when human mode would fail, and they never surface the running-server note.

Additional Locations (1)

• crates/clickhousectl/src/version_manager/install.rs#L185-L190

 

^{Reviewed by Cursor Bugbot for commit c79bf76. Configure here.}