fix: suppress all usage telemetry when opted out
Issue for this PR
Closes #1801
Type of change
- Bug fix
- New feature
- Refactor / code improvement
- Documentation
What does this PR do?
Why: a user who opted out of telemetry could still have events sent. Startup events tracked before the config could be read were flushed anyway, and an opted-out machine sent a final telemetry_opted_out event.
Before → after
- Opted out by
ALTIMATE_TELEMETRY_DISABLED,ALTIMATE_CLI_DISABLE_TELEMETRYorOPENCODE_DISABLE_TELEMETRY(1/true), or bytelemetry.disabledin config: some startup events and the farewell event were sent → nothing is sent, startup events included, and no account lookup is made. The farewell event and its marker files are removed. - Opted in: no change. Startup events are still sent, once the config reads as enabled.
- Config not readable yet (CLI startup before the project config loads, a configured remote or organization config not loaded, an unparseable auth store): events were sent → events are held in the existing 200-event buffer and nothing is sent. A later init sends them if the config reads as enabled, or drops them if it reads as disabled. Inside a project every init reads the already-loaded config (telemetry never forces a config reload); outside one, the files are re-read at most every 30 s. At exit, held events are dropped.
- The auth URL omits the machine ID while the opt-out is disabled or unknown.
- The TUI main thread loads no project, so it cannot read a remote or organization config itself; it adopts the opt-out its worker resolves, including a later opt-out, which stops it.
Design: one process-wide gate (pending, enabled, disabled) on top of main's per-session init/shutdown lifecycle. Tracking drops events only once the gate is disabled, flushing sends only once it is enabled, and disabled holds for the rest of the process. isEnabled() keeps main's meaning. It replaces the earlier per-project scopes, which shut one project's telemetry down mid-turn.
Known gaps. (1) Same as main: in one process that serves an opted-in project B and a project A whose opt-out is set only in A's own project config, events A tracks before its first init resolves can be sent under B's enabled gate. Once A's config resolves, the gate turns off for the whole process. Env-var opt-outs are not affected. (2) Fail-closed: a command that loads no project and has no worker (auth login, tool report-event (the Claude Code plugin's only telemetry path), attach, run --attach), run by a user with an organization selected, a well-known login, or an account database not in WAL mode, and no local setting, holds its events and drops them at exit instead of loading a project to find out. Commands that load a project settle it there, through either CLI project loader. A serve or IDE host in that state that exits before its first project session drops its held startup events the same way. (3) Fail-closed: a failed account or organization config read, or an auth store Auth could not read when the config loaded, holds telemetry until the app reloads its config; a warning is logged.
Declined review suggestion: requiring telemetry to be running before the sign-in URL includes the machine ID. Inside a project the full config read is the decision, and a process-wide opt-out is checked right before the ID is read.
How did you verify your code works?
- New regressions in the telemetry opt-out suite cover: env and config opt-outs send zero requests, startup events included; unreadable then enabled sends held events once; unreadable then disabled sends nothing and stays off; exit while unresolved sends nothing; two opted-in projects share one lifecycle and lose no events; TUI adoption of the worker's decision; a closed WAL account database without side files (Linux, Windows); one project's unreadable config never holds up or leaks into another project's session.
- On detached origin/main, 18 of the first 20 opt-out cases fail (farewell event sent, held events flushed). On the previous head 4fcf5c06, the two-project case fails because project A's telemetry is off mid-turn, and the throttle, session-shutdown and sticky-disable cases fail too.
- Locally: the telemetry-related run passes (the only failures are a project-scan test that also fails on main and load timeouts that pass alone), plus bun typecheck, the strict marker check and the tracker-leak check. Pushes used --no-verify after running the hook's checks directly.
- Local Claude reviews (Codex is out of quota) ran on each pushed head; every P0–P2 was fixed, and the last rounds found only P3s. Every review thread has a reply. Last reviewed head: afb0a5c4d44 (no P0/P1; its one P2 is the WAL case disclosed above); later commits simplify.
Cost side effects
None.
Screenshots / recordings
N/A
Checklist
- I have tested my changes locally
- I have not included unrelated changes in this PR
- I checked for cost side effects (model calls, queries or cloud resources that grow with user data) and described them, or wrote "none"
🤖 Generated with Claude Code
[!NOTE]
Medium Risk
Touches authentication context, config loading, and all telemetry/network paths with nuanced multi-project and TUI threading; behavior is fail-closed but complex edge cases remain documented.
Overview
Fixes a privacy bug where opting out still allowed telemetry traffic—including startup events flushed before config loaded and a one-shot telemetry_opted_out “farewell” event with on-disk marker files.
Telemetry now uses a process-wide opt-out gate (pending → enabled | disabled). While pending (unreadable/missing config, remote org, or auth sources), events stay in the existing buffer and no ingest or /users/me calls run; disabled drops everything for the rest of the process. The farewell event and opt-out.ts marker/claim logic are removed.
Opt-out resolution is centralized in TelemetryConfig: env flags ALTIMATE_TELEMETRY_DISABLED, ALTIMATE_CLI_DISABLE_TELEMETRY, and OPENCODE_DISABLE_TELEMETRY (1/true), plus merged file/org/managed config, with fail-closed handling for unreadable auth, failed org fetches, and legacy global TOML. Config and Auth now flag when telemetry settings may still be unresolved.
CLI auth (buildCliContext) and debug bundle telemetry facts follow the same rules; the sign-in URL omits machine_id when disabled or unresolved. TUI main thread adopts the worker’s settled opt-out via RPC; bootstrap / effect CLI call Telemetry.settleInProject() after project load.
Docs (security-faq, telemetry) describe the new behavior and removed event.
Reviewed by Cursor Bugbot for commit 37dbb3a1649503f48eb60dc71bdcadfffeca7044. Bugbot is set up for automated code reviews on this repo. Configure here.