[codex] Structure telemetry identity errors

[juliusmarminge]

Summary

• split telemetry identity failures into structured read, decode, generate, persist, and hash errors with source/path/operation context
• preserve the original cause chain while keeping messages independent from cause text
• recover provider sources with catchTags, treating only NotFound as absence and refusing to overwrite the anonymous-id path after other read failures
• log the structured wrapper before falling back to the next identity source

Tests

• vp test apps/server/src/telemetry/Identify.test.ts
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

---

Note

Medium Risk
Changes how telemetry user IDs are derived and persisted when auth files are missing or corrupt; mis-handling could affect analytics identity stability but scope is limited to telemetry identification.

Overview
Replaces the single hash error with typed telemetry identity errors (read, decode, generate, persist, hash) that keep the original cause but use fixed messages that do not echo nested cause text.

getTelemetryIdentifierForHome resolves codex → claude → anonymous: only NotFound counts as “missing”; other read failures are logged with structured annotations (errorTag, source, filePath, causeKind, no raw cause or secrets) and the flow falls through to the next source. upsertAnonymousId reuses an existing file when readable and does not write a new anonymous id after a non-NotFound read failure (can return null instead of minting an id). getTelemetryIdentifier delegates to the new home-directory API.

Adds Identify.test.ts for anonymous reuse, malformed Codex JSON fallback/logging, and directory-at-anonymous-path behavior.

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

Note

Structure telemetry identity errors with typed error classes and source-aware logging

• Replaces generic error handling in Identify.ts with typed error classes (TelemetryIdentityReadError, TelemetryIdentityDecodeError, TelemetryAnonymousIdGenerationError, TelemetryAnonymousIdPersistenceError, TelemetryIdentityHashError) that carry source, filePath, and cause fields.
• Adds logTelemetryIdentityError to emit structured warnings with consistent annotations (errorTag, source, causeKind, platformReason, errorStack).
• NotFound file reads now return Option.none for silent fallback; other read failures propagate as typed errors, preventing anonymous id from being silently overwritten on non-NotFound errors.
• Introduces getTelemetryIdentifierForHome to resolve identity across Codex → Claude → anonymous sources deterministically, returning null when all sources fail.
• Risk: upsertAnonymousId now propagates non-NotFound read failures instead of silently overwriting, which is a behavioral change for degraded filesystem states.

^{Macroscope summarized f7c377b.}

[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: c73e32d2-5fc2-4154-abd9-a798949a35bb

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
• Commit unit tests in branch codex/structure-telemetry-identity-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors telemetry identity error handling to use structured, typed error classes instead of a generic error. The core fallback logic remains unchanged, and comprehensive tests verify the new error structure.

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

[macroscopeapp]

One convention finding on the new telemetry identity error classes. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

Dismissing prior approval to re-evaluate e855c40

Dismissing prior approval to re-evaluate f7c377b