@timo972/cc-router 0.12.1 → 0.12.2-rc.0

package/CHANGELOG.md

@@ -8,6 +8,24 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- Privacy-bounded OpenTelemetry and PostHog EU telemetry: 10%-sampled proxy
+  traces, closed-schema setup and runtime diagnostics, lifecycle events, and
+  sanitized exceptions with diagnostic IDs. Every outbound record is rebuilt
+  from an allowlist immediately before export; prompts, bodies, headers,
+  URLs, account identifiers, tokens, and raw error messages are never sent.
+  Fresh installations default on; `cc-router telemetry off`, `DO_NOT_TRACK=1`,
+  and `CC_ROUTER_TELEMETRY=0` disable every signal, and a running daemon stops
+  exporting as soon as it observes an explicit opt-out. See
+  [docs/telemetry.md](docs/telemetry.md) for the complete inventory.
+
+### Changed
+
+- Aptabase telemetry has been removed. An existing persisted opt-out remains
+  off after upgrade; no PostHog Person profiles are created and GeoIP
+  enrichment is disabled.
+
 ---
 
 ## [0.12.1] — 2026-09-14

package/Dockerfile

@@ -8,6 +8,7 @@ COPY package*.json ./
 RUN npm ci
 
 COPY tsconfig.json ./
+COPY scripts/ ./scripts/
 COPY src/ ./src/
 RUN npm run build
 

package/README.md

@@ -125,7 +125,7 @@ Per-platform token extraction, Codex CLI, Docker and everything else lives in
 | [LiteLLM](docs/litellm-setup.md) | Optional logging and rate-limiting layer |
 | [OAuth tokens](docs/oauth-tokens.md) | How subscription tokens and refresh rotation work |
 | [Security](docs/security.md) | Token storage, proxy auth, threat model |
-| [Telemetry](docs/telemetry.md) | Opt-in analytics: what's sent if you enable it |
+| [Telemetry](docs/telemetry.md) | Privacy-bounded telemetry, on by default: exactly what is sent and how to turn it off |
 | [Troubleshooting](docs/troubleshooting.md) | When something doesn't connect |
 
 ## Disclaimer

package/dist/cli/cmd-accounts.js

@@ -8,6 +8,7 @@ import { loginOpenAIWithDeviceCode } from "../providers/openai/device-oauth.js";
 import { importGrokCliAuth } from "../providers/xai/import-auth.js";
 import { loginXaiWithDeviceCode } from "../providers/xai/device-oauth.js";
 import { isValidAccountId } from "../proxy/account-rename.js";
+import { createSetupAttempt, failAttemptFromError, withSetupTelemetryFlush, } from "../telemetry/setup-diagnostics.js";
 export function registerAccounts(program) {
     const accounts = program
         .command("accounts")
@@ -118,9 +119,9 @@ export function registerAccounts(program) {
         .command("add")
         .description("Add a new Claude Max account interactively")
         .action(async () => {
-        const { setupSingleAccount } = await import("./cmd-setup.js");
+        const { setupSingleAccountWithAttempt } = await import("./cmd-setup.js");
         const existing = accountsFileExists() ? loadAccounts() : [];
-        const account = await setupSingleAccount(existing.length + 1);
+        const { account, attempt } = await setupSingleAccountWithAttempt(existing.length + 1);
         if (!account) {
             console.log(chalk.yellow("\nNo account added.\n"));
             return;
@@ -130,10 +131,19 @@ export function registerAccounts(program) {
             ...existing.filter(a => a.id !== account.id),
             account,
         ];
-        const { mode } = await addAccountRuntimeAware(serialize([account])[0], {
-            tryAddLive: tryAddAccountToRunningProxy,
-            addStored: () => saveAccounts(merged),
-        });
+        let mode;
+        try {
+            ({ mode } = await addAccountRuntimeAware(serialize([account])[0], {
+                tryAddLive: tryAddAccountToRunningProxy,
+                addStored: () => saveAccounts(merged),
+            }));
+        }
+        catch (error) {
+            endFailedAttempt(attempt, error, "persistence");
+            throw error;
+        }
+        attempt.stageCompleted("persistence");
+        attempt.succeeded();
         console.log(chalk.green(`\n✓ Account "${account.id}" added (${merged.length} total).\n`));
         printAddOutcome(mode);
     });
@@ -141,71 +151,101 @@ export function registerAccounts(program) {
     accounts
         .command("add-openai")
         .description("Add an OpenAI ChatGPT/Codex subscription account manually")
-        .action(async () => {
+        .action(async () => withSetupTelemetryFlush(async () => {
         const { input, password } = await import("@inquirer/prompts");
-        const id = await input({
-            message: "OpenAI account ID:",
-            default: `openai-account-${loadOpenAIAccounts().length + 1}`,
-            validate: (v) => /^[a-zA-Z0-9_-]+$/.test(v) || "Only letters, numbers, _ and - allowed",
-        });
-        const accessToken = await password({
-            message: "OpenAI access token:",
-            mask: "*",
-            validate: (v) => v.trim().length > 0 || "Access token is required",
-        });
-        const refreshToken = await password({
-            message: "OpenAI refresh token:",
-            mask: "*",
-            validate: (v) => v.trim().length > 0 || "Refresh token is required",
-        });
-        const expiresAt = await input({
-            message: "Access token expiry (Unix ms):",
-            default: String(Date.now() + 60 * 60 * 1000),
-            validate: (v) => Number.isFinite(Number(v)) && Number(v) > 0 || "Enter a positive Unix timestamp in milliseconds",
-        });
-        const scopes = await input({
-            message: "Scopes:",
-            default: "openid profile email offline_access",
-        });
-        const record = createOpenAIAccountRecord({
-            id,
-            accessToken,
-            refreshToken,
-            expiresAt,
-            scopes,
-        });
-        const { mode } = await addAccountRuntimeAware(record);
-        console.log(chalk.green(`\n✓ OpenAI account "${record.id}" saved.\n`));
-        printAddOutcome(mode);
-        console.log(chalk.yellow("  Treat this as experimental until the OAuth login wizard lands.\n"));
-    });
+        const attempt = createSetupAttempt({ provider: "openai", method: "manual_token" });
+        attempt.stageCompleted("credential_source_selection");
+        let reached = "credential_read";
+        try {
+            const id = await input({
+                message: "OpenAI account ID:",
+                default: `openai-account-${loadOpenAIAccounts().length + 1}`,
+                validate: (v) => /^[a-zA-Z0-9_-]+$/.test(v) || "Only letters, numbers, _ and - allowed",
+            });
+            const accessToken = await password({
+                message: "OpenAI access token:",
+                mask: "*",
+                validate: (v) => v.trim().length > 0 || "Access token is required",
+            });
+            const refreshToken = await password({
+                message: "OpenAI refresh token:",
+                mask: "*",
+                validate: (v) => v.trim().length > 0 || "Refresh token is required",
+            });
+            const expiresAt = await input({
+                message: "Access token expiry (Unix ms):",
+                default: String(Date.now() + 60 * 60 * 1000),
+                validate: (v) => Number.isFinite(Number(v)) && Number(v) > 0 || "Enter a positive Unix timestamp in milliseconds",
+            });
+            const scopes = await input({
+                message: "Scopes:",
+                default: "openid profile email offline_access",
+            });
+            attempt.stageCompleted("credential_read");
+            reached = "credential_parse";
+            const record = createOpenAIAccountRecord({
+                id,
+                accessToken,
+                refreshToken,
+                expiresAt,
+                scopes,
+            });
+            attempt.stageCompleted("credential_parse");
+            reached = "persistence";
+            const { mode } = await addAccountRuntimeAware(record);
+            attempt.stageCompleted("persistence");
+            attempt.succeeded();
+            console.log(chalk.green(`\n✓ OpenAI account "${record.id}" saved.\n`));
+            printAddOutcome(mode);
+            console.log(chalk.yellow("  Treat this as experimental until the OAuth login wizard lands.\n"));
+        }
+        catch (error) {
+            endFailedAttempt(attempt, error, reached);
+            throw error;
+        }
+    }));
     // ── accounts login-openai ────────────────────────────────────────────────
     accounts
         .command("login-openai")
         .description("Sign in to an OpenAI ChatGPT/Codex subscription account with device code")
-        .action(async () => {
+        .action(async () => withSetupTelemetryFlush(async () => {
         const { input } = await import("@inquirer/prompts");
-        const accountId = await input({
-            message: "OpenAI account ID:",
-            default: `openai-account-${loadOpenAIAccounts().length + 1}`,
-            validate: (v) => /^[a-zA-Z0-9_-]+$/.test(v) || "Only letters, numbers, _ and - allowed",
-        });
-        console.log(chalk.cyan("\nOpenAI Codex device login"));
-        console.log(chalk.gray("This will open no local callback server. You will approve the login in your browser.\n"));
-        const record = await loginOpenAIWithDeviceCode({
-            accountId,
-            onDeviceCode: (code) => {
-                console.log(chalk.bold("1. Open this URL:"));
-                console.log(`   ${chalk.cyan(code.verificationUrl)}`);
-                console.log(chalk.bold("2. Enter this code:"));
-                console.log(`   ${chalk.cyan(code.userCode)}\n`);
-                console.log(chalk.gray("Waiting for authorization..."));
-            },
-        });
-        const { mode } = await addAccountRuntimeAware(record);
-        console.log(chalk.green(`\n✓ OpenAI account "${record.id}" saved via device login.\n`));
-        printAddOutcome(mode);
-    });
+        const attempt = createSetupAttempt({ provider: "openai", method: "device_oauth" });
+        let reached = "device_code_request";
+        try {
+            const accountId = await input({
+                message: "OpenAI account ID:",
+                default: `openai-account-${loadOpenAIAccounts().length + 1}`,
+                validate: (v) => /^[a-zA-Z0-9_-]+$/.test(v) || "Only letters, numbers, _ and - allowed",
+            });
+            console.log(chalk.cyan("\nOpenAI Codex device login"));
+            console.log(chalk.gray("This will open no local callback server. You will approve the login in your browser.\n"));
+            const record = await loginOpenAIWithDeviceCode({
+                accountId,
+                onDeviceCode: (code) => {
+                    console.log(chalk.bold("1. Open this URL:"));
+                    console.log(`   ${chalk.cyan(code.verificationUrl)}`);
+                    console.log(chalk.bold("2. Enter this code:"));
+                    console.log(`   ${chalk.cyan(code.userCode)}\n`);
+                    console.log(chalk.gray("Waiting for authorization..."));
+                },
+                onStageCompleted: (stage) => {
+                    attempt.stageCompleted(stage);
+                    reached = stage;
+                },
+            });
+            reached = "persistence";
+            const { mode } = await addAccountRuntimeAware(record);
+            attempt.stageCompleted("persistence");
+            attempt.succeeded();
+            console.log(chalk.green(`\n✓ OpenAI account "${record.id}" saved via device login.\n`));
+            printAddOutcome(mode);
+        }
+        catch (error) {
+            endFailedAttempt(attempt, error, reached);
+            throw error;
+        }
+    }));
     // ── accounts add-grok ────────────────────────────────────────────────────
     accounts
         .command("add-grok")
@@ -345,6 +385,17 @@ export function registerAccounts(program) {
     });
 }
 // ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Close a setup attempt that ended in a thrown error. A cancelled prompt is a
+ * user decision, not a failure, and only an unexpected failure gets a
+ * diagnostic ID worth quoting in a bug report.
+ */
+function endFailedAttempt(attempt, error, fallbackStage) {
+    const outcome = failAttemptFromError(attempt, error, fallbackStage);
+    if (outcome?.unexpected) {
+        console.log(chalk.gray(`  Diagnostic ID: ${outcome.diagnosticId}`));
+    }
+}
 /** Tell the user whether the new account is already live or needs a restart. */
 function printAddOutcome(mode) {
     console.log(mode === "live"

package/dist/cli/cmd-setup.js

@@ -1,7 +1,7 @@
 import { select, input, confirm, password } from "@inquirer/prompts";
 import chalk from "chalk";
 import { detectPlatform, isMacos } from "../utils/platform.js";
-import { extractFromKeychain, extractFromCredentialsFile, formatExpiry, redactToken, } from "../utils/token-extractor.js";
+import { extractFromKeychainDetailed, extractFromCredentialsFileDetailed, formatExpiry, redactToken, } from "../utils/token-extractor.js";
 import { validateToken } from "../utils/token-validator.js";
 import { writeClaudeSettings, readClaudeProxySettings } from "../utils/claude-config.js";
 import { saveAccounts } from "../proxy/token-refresher.js";
@@ -11,7 +11,7 @@ import { DEFAULT_RATE_LIMITS, ACCOUNT_USER_DEFAULTS } from "../proxy/types.js";
 import { existsSync } from "fs";
 import { checkMitmproxyInstalled, isCaCertInstalled, generateCaCert, installCaCert, writeAddonScript, getNetworkExtensionStatus, openNetworkExtensionSettings, } from "../interceptor/mitmproxy-manager.js";
 import { printDesktopSupportExplainer, printNetworkExtensionInstructions } from "./cmd-client.js";
-import { trackEvent } from "../utils/telemetry.js";
+import { createSetupAttempt, failAttemptFromError, withSetupTelemetryFlush, } from "../telemetry/setup-diagnostics.js";
 // ─── Public registration ──────────────────────────────────────────────────────
 export function registerSetup(program) {
     program
@@ -19,11 +19,21 @@ export function registerSetup(program) {
         .description("Interactive wizard: extract tokens and configure Claude Code automatically")
         .option("--add", "Add a new account to an existing configuration (skip intro questions)")
         .action(async (opts) => {
-        await runSetupWizard({ addMode: opts.add ?? false });
+        await withSetupTelemetryFlush(() => runSetupWizard({ addMode: opts.add ?? false }));
     });
 }
+/** Only an unexpected failure gets a diagnostic ID worth quoting in a bug report. */
+function printDiagnosticId(outcome) {
+    if (!outcome.unexpected)
+        return;
+    console.log(chalk.gray(`  Diagnostic ID: ${outcome.diagnosticId}`));
+}
 // ─── Shared single-account setup (also used by `accounts add`) ───────────────
-export async function setupSingleAccount(index) {
+/**
+ * Same step, but also hands back the setup attempt so the caller can mark the
+ * `persistence` stage and the final outcome once the account is written.
+ */
+export async function setupSingleAccountWithAttempt(index) {
     const choices = [];
     if (isMacos()) {
         choices.push({ name: "Extract automatically from macOS Keychain  (recommended)", value: "keychain" });
@@ -34,11 +44,35 @@ export async function setupSingleAccount(index) {
         message: "How do you want to add the tokens?",
         choices,
     });
+    const attempt = createSetupAttempt({
+        provider: "anthropic",
+        method: method === "keychain"
+            ? "macos_keychain"
+            : method === "credentials" ? "claude_credentials_file" : "manual_token",
+    });
+    attempt.stageCompleted("credential_source_selection");
+    // Shared by reference: the file-extraction fallback swaps in a manual-token attempt.
+    const current = { attempt };
+    let reached = "credential_read";
+    try {
+        return await collectAnthropicAccount(index, method, current, stage => { reached = stage; });
+    }
+    catch (error) {
+        // A thrown prompt or extraction error must still close the funnel record.
+        const outcome = failAttemptFromError(current.attempt, error, reached);
+        if (outcome)
+            printDiagnosticId(outcome);
+        throw error;
+    }
+}
+async function collectAnthropicAccount(index, method, current, reached) {
+    let attempt = current.attempt;
     let tokens = null;
     if (method === "keychain") {
         process.stdout.write(chalk.gray("  Extracting from Keychain... "));
-        tokens = await extractFromKeychain();
-        if (tokens) {
+        const extraction = await extractFromKeychainDetailed();
+        if (extraction.ok) {
+            tokens = extraction.tokens;
             console.log(chalk.green("✓"));
             console.log(chalk.gray(`  Token: ${redactToken(tokens.accessToken)}`));
             console.log(chalk.gray(`  Expiry: ${formatExpiry(tokens.expiresAt)}`));
@@ -47,15 +81,18 @@ export async function setupSingleAccount(index) {
             console.log(chalk.red("✗"));
             console.log(chalk.yellow("  Could not find credentials in Keychain."));
             console.log(chalk.gray("  Make sure Claude Code is logged in: run `claude login` first."));
+            printDiagnosticId(attempt.stageFailed(extraction.error, "credential_read"));
             const retry = await confirm({ message: "Try another extraction method?", default: true });
+            attempt.cancelled();
             if (!retry)
-                return null;
-            return setupSingleAccount(index);
+                return { account: null, attempt };
+            return setupSingleAccountWithAttempt(index);
         }
     }
     if (method === "credentials") {
-        tokens = extractFromCredentialsFile();
-        if (tokens) {
+        const extraction = extractFromCredentialsFileDetailed();
+        if (extraction.ok) {
+            tokens = extraction.tokens;
             console.log(chalk.green(`  ✓ Found credentials in ~/.claude/.credentials.json`));
             console.log(chalk.gray(`    Token: ${redactToken(tokens.accessToken)}`));
             console.log(chalk.gray(`    Expiry: ${formatExpiry(tokens.expiresAt)}`));
@@ -64,16 +101,29 @@ export async function setupSingleAccount(index) {
             console.log(chalk.red("  ✗ ~/.claude/.credentials.json not found or unreadable."));
             console.log(chalk.gray("  Make sure Claude Code is installed and you've run `claude login`."));
             const retry = await confirm({ message: "Paste tokens manually instead?", default: true });
-            if (!retry)
-                return null;
+            if (!retry) {
+                printDiagnosticId(attempt.stageFailed(extraction.error, "credential_read"));
+                attempt.cancelled();
+                return { account: null, attempt };
+            }
+            // The file-based attempt failed; the pasted tokens are a manual-token setup.
+            printDiagnosticId(attempt.failed(extraction.error, "credential_read"));
+            attempt = createSetupAttempt({ provider: "anthropic", method: "manual_token" });
+            current.attempt = attempt;
+            attempt.stageCompleted("credential_source_selection");
             tokens = await promptManualTokens();
         }
     }
     if (method === "manual") {
         tokens = await promptManualTokens();
     }
-    if (!tokens)
-        return null;
+    if (!tokens) {
+        attempt.cancelled();
+        return { account: null, attempt };
+    }
+    attempt.stageCompleted("credential_read");
+    attempt.stageCompleted("credential_parse");
+    reached("token_validation");
     const defaultId = `max-account-${index}`;
     const accountId = await input({
         message: "Account ID (press Enter to accept default):",
@@ -84,27 +134,34 @@ export async function setupSingleAccount(index) {
     const validation = await validateToken(tokens.accessToken);
     if (validation.valid) {
         console.log(chalk.green("✓ Valid"));
+        attempt.stageCompleted("token_validation");
     }
     else {
         console.log(chalk.red("✗ Invalid"));
         console.log(chalk.yellow(`  Reason: ${validation.reason}`));
+        printDiagnosticId(attempt.stageFailed(validation.diagnostic, "token_validation"));
         console.log(chalk.gray("  The token will be saved but may not work until refreshed."));
         const keepAnyway = await confirm({ message: "Save this account anyway?", default: false });
-        if (!keepAnyway)
-            return null;
+        if (!keepAnyway) {
+            attempt.cancelled();
+            return { account: null, attempt };
+        }
     }
     return {
-        id: accountId,
-        tokens,
-        healthy: validation.valid,
-        busy: false,
-        requestCount: 0,
-        errorCount: 0,
-        lastUsed: 0,
-        lastRefresh: 0,
-        consecutiveErrors: 0,
-        rateLimits: { ...DEFAULT_RATE_LIMITS },
-        ...ACCOUNT_USER_DEFAULTS,
+        account: {
+            id: accountId,
+            tokens,
+            healthy: validation.valid,
+            busy: false,
+            requestCount: 0,
+            errorCount: 0,
+            lastUsed: 0,
+            lastRefresh: 0,
+            consecutiveErrors: 0,
+            rateLimits: { ...DEFAULT_RATE_LIMITS },
+            ...ACCOUNT_USER_DEFAULTS,
+        },
+        attempt,
     };
 }
 // ─── Full wizard ──────────────────────────────────────────────────────────────
@@ -179,6 +236,7 @@ export async function runSetupWizard({ addMode }) {
         }) ?? 1;
     }
     const newAccounts = [];
+    const savedAttempts = [];
     for (let i = 0; i < numAccounts; i++) {
         const label = numAccounts > 1 ? `${i + 1}/${numAccounts}` : "";
         console.log(chalk.bold(`\n${"━".repeat(40)}\n  Account ${label}\n${"━".repeat(40)}\n`));
@@ -189,9 +247,10 @@ export async function runSetupWizard({ addMode }) {
             await confirm({ message: "Ready?", default: true });
         }
         const existingCount = hasExisting ? loadAccounts().length : 0;
-        const account = await setupSingleAccount(i + 1 + existingCount);
+        const { account, attempt } = await setupSingleAccountWithAttempt(i + 1 + existingCount);
         if (account) {
             newAccounts.push(account);
+            savedAttempts.push(attempt);
             console.log(chalk.green(`\n  ✓ Account "${account.id}" ready.\n`));
         }
         else {
@@ -209,9 +268,20 @@ export async function runSetupWizard({ addMode }) {
         ...newAccounts,
     ];
     console.log(chalk.bold(`\n${"━".repeat(40)}\n  Saving\n${"━".repeat(40)}\n`));
-    saveAccounts(merged);
+    try {
+        saveAccounts(merged);
+    }
+    catch (error) {
+        const outcomes = savedAttempts.map(attempt => attempt.failed(error, "persistence"));
+        if (outcomes[0])
+            printDiagnosticId(outcomes[0]);
+        throw error;
+    }
     console.log(chalk.green(`  ✓ ${merged.length} account(s) saved to ~/.cc-router/accounts.json`));
-    void trackEvent("setup_completed", { account_count: merged.length });
+    for (const attempt of savedAttempts) {
+        attempt.stageCompleted("persistence");
+        attempt.succeeded();
+    }
     // ─── Post-setup interactive flow ─────────────────────────────────────────
     await runPostSetupFlow(merged.length);
 }

package/dist/cli/cmd-status.js

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { PROXY_PORT } from "../config/paths.js";
 import { readConfig } from "../config/manager.js";
+import { classifyHttpSetupFailure, failAttemptFromError, } from "../telemetry/setup-diagnostics.js";
 export function resolveStatusTarget(port) {
     const cfg = readConfig();
     if (cfg.client) {
@@ -143,10 +144,13 @@ async function dashboardLoop(port) {
  * success, or null if the user aborted / an error occurred.
  */
 async function runAddAccountFlow(target) {
+    let attempt;
     try {
-        const { setupSingleAccount } = await import("./cmd-setup.js");
+        const { setupSingleAccountWithAttempt } = await import("./cmd-setup.js");
         // The index shown in the flow is just for display, pick something neutral.
-        const account = await setupSingleAccount(1);
+        const setup = await setupSingleAccountWithAttempt(1);
+        attempt = setup.attempt;
+        const account = setup.account;
         if (!account)
             return null;
         const res = await fetch(`${target.baseUrl}/cc-router/accounts`, {
@@ -169,12 +173,20 @@ async function runAddAccountFlow(target) {
             console.error(chalk.red(`\n✗ Server rejected account: HTTP ${res.status}`));
             if (text)
                 console.error(chalk.gray(`  ${text}`));
+            attempt.failed(classifyHttpSetupFailure("persistence", res.status, "dashboard account add rejected"), "persistence");
             return null;
         }
+        attempt.stageCompleted("persistence");
+        attempt.succeeded();
         return account.id;
     }
     catch (err) {
         console.error(chalk.red(`\n✗ Failed to add account: ${err.message}`));
+        if (attempt) {
+            const outcome = failAttemptFromError(attempt, err, "persistence");
+            if (outcome?.unexpected)
+                console.error(chalk.gray(`  Diagnostic ID: ${outcome.diagnosticId}`));
+        }
         return null;
     }
 }

package/dist/cli/cmd-telemetry.js

@@ -1,57 +1,68 @@
 import chalk from "chalk";
-import { loadTelemetryState, writeTelemetryState, isTelemetryEnabled } from "../config/telemetry.js";
+import { getTelemetrySnapshot, updateTelemetryConsent } from "../config/telemetry.js";
 export function registerTelemetry(program) {
     program
         .command("telemetry [action]")
-        .description("Manage anonymous usage analytics: on, off, status (default: status)")
+        .description("Manage privacy-safe telemetry: on, off, status (default: status; fresh installs: on)")
         .action(async (action) => {
         const resolved = action ?? "status";
-        if (resolved === "status") {
-            showStatus();
-            return;
+        try {
+            runTelemetryAction(resolved);
         }
-        if (resolved === "on") {
-            const state = loadTelemetryState();
-            state.enabled = true;
-            writeTelemetryState(state);
-            console.log(chalk.green("Telemetry enabled."));
-            console.log(chalk.dim(`Install ID: ${state.installId}`));
-            return;
+        catch (error) {
+            // An unreadable state file keeps telemetry off; never replace it blindly.
+            console.error(chalk.red(error instanceof Error ? error.message : "Telemetry state could not be read."));
+            console.error(chalk.dim("Telemetry stays disabled until the file is readable again."));
+            process.exitCode = 1;
         }
-        if (resolved === "off") {
-            // Do not beacon on opt-out: an explicit "turn it off" must not send data.
-            const state = loadTelemetryState();
-            state.enabled = false;
-            writeTelemetryState(state);
-            console.log(chalk.yellow("Telemetry disabled. No data will be sent."));
-            console.log(chalk.dim("Re-enable anytime with: cc-router telemetry on"));
-            return;
-        }
-        console.error(chalk.red(`Unknown action "${resolved}". Use: on, off, status`));
-        process.exitCode = 1;
     });
 }
+function runTelemetryAction(resolved) {
+    if (resolved === "status") {
+        showStatus();
+        return;
+    }
+    if (resolved === "on") {
+        const state = updateTelemetryConsent(true);
+        console.log(chalk.green("Telemetry enabled for future daemon starts."));
+        console.log(chalk.dim("Restart a daemon that started with telemetry disabled to begin sending telemetry."));
+        console.log(chalk.dim(`Install ID: ${state.installId}`));
+        return;
+    }
+    if (resolved === "off") {
+        // Do not beacon on opt-out: an explicit "turn it off" must not send data.
+        updateTelemetryConsent(false);
+        console.log(chalk.yellow("Telemetry disabled. New outbound telemetry stops immediately."));
+        console.log(chalk.dim("Re-enable anytime with: cc-router telemetry on"));
+        return;
+    }
+    console.error(chalk.red(`Unknown action "${resolved}". Use: on, off, status`));
+    process.exitCode = 1;
+}
 function showStatus() {
-    const state = loadTelemetryState();
-    const envDisabled = process.env["DO_NOT_TRACK"] === "1" || process.env["CC_ROUTER_TELEMETRY"] === "0";
+    const { state, environmentDisabled, enabled } = getTelemetrySnapshot();
     console.log(chalk.bold("Telemetry"));
     console.log();
-    if (envDisabled) {
+    if (environmentDisabled) {
         console.log(`  Status:     ${chalk.yellow("disabled")} (by environment variable)`);
     }
     else if (state.enabled) {
-        console.log(`  Status:     ${chalk.green("enabled")}`);
+        console.log(`  Status:     ${chalk.green("enabled")} (persisted)`);
     }
     else {
-        console.log(`  Status:     ${chalk.yellow("disabled")}`);
+        console.log(`  Status:     ${chalk.yellow("disabled")} (persisted)`);
     }
-    console.log(`  Active:     ${isTelemetryEnabled() ? chalk.green("yes") : chalk.yellow("no")}`);
+    console.log(`  Active:     ${enabled ? chalk.green("yes") : chalk.yellow("no")}`);
     console.log(`  Install ID: ${chalk.dim(state.installId)}`);
     console.log(`  Since:      ${chalk.dim(state.firstRunAt)}`);
     console.log();
-    console.log(chalk.dim("  What we send:  version, OS, locale, lifecycle events (start, heartbeat)"));
-    console.log(chalk.dim("  What we DON'T: IPs, tokens, prompts, request content, account names"));
-    console.log(chalk.dim("  Source code:   src/utils/telemetry.ts"));
+    console.log(chalk.dim("  What we send:  sampled traces, safe diagnostics, lifecycle events, sanitized exceptions"));
+    console.log(chalk.dim("  What we DON'T: tokens, prompts/content, account/session IDs, raw errors, URLs, headers"));
+    console.log(chalk.dim("  Network note:   PostHog EU sees the HTTPS source IP; it is not added to the payload"));
+    console.log(chalk.dim("  Identity:       random install pseudonym; no Person profile or GeoIP enrichment"));
+    console.log(chalk.dim("  Source code:   src/telemetry/"));
+    console.log(chalk.dim("  Inventory:     docs/telemetry.md"));
+    console.log(chalk.dim("  Default:       on for new installs"));
     console.log();
     console.log(chalk.dim("  Disable:  cc-router telemetry off"));
     console.log(chalk.dim("  Or set:   DO_NOT_TRACK=1  |  CC_ROUTER_TELEMETRY=0"));