fix(server): Make telemetry configurable and opt-in

[mwolson]

Summary

• Make PostHog telemetry opt-in from both server configuration and the Settings UI.
• Keep the existing T3CODE_TELEMETRY_ENABLED=true environment override for explicit opt-in.
• Add a Telemetry switch in Settings near Diagnostics.
• Avoid resolving telemetry identifiers, creating fallback anonymous IDs, buffering events, or sending batches while telemetry is disabled.
• Downgrade telemetry flush failures from error logging to debug logging so blocked PostHog endpoints do not spam application logs.

Addresses #1397.

Problem and Fix

Problem and Why it Happened	Fix
The marketing page says "No telemetry" and "Unless you opt in", but the server default enabled telemetry unless users knew to set T3CODE_TELEMETRY_ENABLED=false.	Default telemetry to disabled and only enable it when the environment override is true or the persisted Settings value is true.
Disabling telemetry after startup still needed to avoid event buffering, identifier lookup, and batch sending.	Gate both record and flush through the current telemetry setting and clear buffered events when telemetry is disabled.
Users had no visible app setting for telemetry.	Add a Telemetry switch in the General Settings About section near Diagnostics.
Blocked or unreachable PostHog endpoints could repeatedly log ERROR: Failed to flush telemetry.	Log telemetry flush failures at debug level.

UI Changes

The new Telemetry setting appears in Settings near Diagnostics.

Screenshot is also available in this PR comment.

Validation

• pnpm exec vp test run packages/contracts/src/settings.test.ts apps/server/src/serverSettings.test.ts apps/server/src/telemetry/Layers/AnalyticsService.test.ts
• pnpm --filter @t3tools/web test:browser -- src/components/settings/SettingsPanels.browser.tsx
• pnpm exec vp run typecheck
• pnpm exec vp check (passed with existing unrelated lint warnings)
• Built Linux AppImage with pnpm run dist:desktop:linux.
• Ran release/T3-Code-0.0.27-x86_64.AppImage and confirmed the Telemetry setting appears near Diagnostics with default value off.
• With Telemetry off, triggered a trivial General mode response and confirmed the app had no telemetryEnabled persisted override, no fallback anonymous-id, no sendBatch spans, and no current-run PostHog or telemetry flush log entries.
• Turned Telemetry on, sent more messages, switched to Plan mode, triggered a choice picker, and selected an option. Confirmed telemetryEnabled: true was persisted and successful sendBatch spans were emitted.
• Turned Telemetry off again, triggered one more Plan mode chooser and one more trivial General mode response. Confirmed new record spans reached the telemetry gate but no new sendBatch spans were emitted after disabling telemetry again.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes (not applicable, no animation or interaction changes)

Note

Make telemetry opt-in by default and expose a toggle in the Settings UI

• Telemetry is now disabled by default; users must explicitly opt in via a new toggle in the General Settings panel, which sets telemetryEnabled and telemetryPreferenceSet in ServerSettings.
• AnalyticsService reads ServerSettings.telemetryEnabled to gate all recording and flushing; events are buffered but not sent when disabled, and batches are re-queued on settings read failures or missing identifiers.
• Environment variable T3CODE_TELEMETRY_ENABLED=true can seed an opt-in when no saved preference exists, but cannot override an explicit user opt-out.
• normalizeDecodedPersistedServerSettings detects a previously persisted telemetryEnabled value in raw JSON and marks telemetryPreferenceSet=true, preserving existing preferences across schema changes.
• Risk: any deployment where telemetry was previously enabled by default will now have telemetry disabled until users explicitly opt in.

^{Macroscope summarized 36c175b.}

---

Note

Medium Risk
Changes default telemetry behavior and preference precedence (env vs persisted settings), which affects privacy expectations and existing installs that relied on implicit opt-in without the env var.

Overview
PostHog telemetry is opt-in by default instead of being enabled unless T3CODE_TELEMETRY_ENABLED=false. Server settings gain telemetryEnabled and telemetryPreferenceSet, with load/patch helpers so a saved choice (including opt-out) sticks and legacy settings.json that mentions telemetryEnabled counts as an explicit preference.

AnalyticsService now decides whether to record, resolve an anonymous ID, or flush from persisted settings: disabled telemetry skips buffering and network I/O; T3CODE_TELEMETRY_ENABLED=true can seed opt-in when no preference exists; false forces off over a saved opt-in; explicit user opt-out is not overridden by env. Flush paths clear or retain buffers when telemetry turns off or settings/identifier reads fail; flush errors log at debug instead of error.

The General Settings UI adds a Telemetry switch (sets preference on toggle), reset/restore-defaults handling via buildRestoreDefaultsPatch, and CLI integration tests wire in ServerSettingsService.layerTest().

^{Reviewed by Cursor Bugbot for commit cc577a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 0e0d62ef-e8b0-4018-9ef9-b00126022d39

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mwolson]

Screenshot of new setting

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR changes telemetry from enabled-by-default to opt-in, which is a significant runtime behavior change affecting data collection. The scope of behavioral modification to the analytics system warrants human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[macroscopeapp]

One Effect service-convention violation in the telemetry service. See inline comments.

^{Posted via Macroscope — Effect Service Conventions}

[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, enable autofix in the Cursor dashboard.}

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