## TL;DR
The agent updated image snapshots on macOS, baking in macOS font rendering, and they fail on Linux CI. Regenerate snapshot baselines on the same platform CI uses (Linux), or keep per-platform baselines. Never accept a snapshot update generated on a different OS than the one that runs the tests.

## The symptom
```text
agent's snapshot update ran on macOS  -  the font rendering baked in fails on CI's Linux screenshots
```

## Steps
### 1. Confirm the platform mismatch
Compare the failing snapshot diff: if the differences are subpixel font-rendering variations rather than layout changes, it is the platform, not the UI.
Expected: Diffs concentrated in text glyphs, layout identical.

### 2. Regenerate baselines on Linux
Run the snapshot update on a Linux machine (or the CI job itself) and commit those baselines. The macOS-generated files are invalid for Linux CI.
Expected: Snapshots generated under Linux font rendering.

### 3. Verify on CI
Push the Linux-generated baselines and run the CI job. The screenshot tests should pass.
Expected: Green screenshot tests on Linux CI.

### 4. Pin snapshot generation to the CI platform
Make snapshot updates a CI-side operation (or a Linux container step), and teach the healer to refuse cross-platform snapshot updates.
Expected: No future snapshot update from the wrong OS.

## When to use
- Image snapshots updated on macOS fail on Linux CI
- Diffs show font-rendering noise, not layout changes
- The agent's sandbox OS differs from CI's

## When not to use
- Snapshots are text-based (platform-independent)
- The diff shows real layout changes (that is a genuine UI change to review)
- CI and the sandbox are the same OS (different cause)

## Why it happens
Font rendering differs between macOS and Linux (different rasterizers, hinting, and system fonts). Image snapshots capture pixels, so a macOS-baked baseline can never match Linux rendering. The agent did the update correctly for the wrong platform.

## Edge cases
- Per-platform baselines: name them by OS when the suite must run on both.
- Containerized browsers: pin the browser and font versions too, not just the OS.
- DPR and scaling differences: standardize those alongside the platform.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_iHaKY56nBfyf2N1dMi2-1A