## TL;DR
CI shards the suite, and the failing test uses a global counter that collides when shards run in parallel. The test passes locally because nothing else touches the counter. Replace shared global state with per-test unique values (UUIDs, PIDs, random suffixes) and verify under the same sharding CI uses.

## The symptom
```text
agent didn't know CI shards the suite  -  the failing test depends on a global counter that only collides under sharding
```

## Steps
### 1. Confirm sharding is the trigger
Run the test unsharded: passes. Run with CI's sharding (same shard count and assignment): fails. The counter collision only happens in parallel.
Expected: Failure reproduces only under sharding.

### 2. Find the shared state
Search the test and its fixtures for globals, static counters, fixed ports, hardcoded temp paths, or shared sequence names.
Expected: The global counter (or equivalent) identified.

### 3. Make it unique per test
Replace the fixed value with a unique one per test run: UUID suffixes, process IDs, or isolated namespaces.
Expected: No two tests can collide on the value.

### 4. Verify under CI sharding
Rerun with the exact shard configuration. The test passes alone, in shards, and in the full suite.
Expected: Green across all sharding configurations.

## When to use
- Test passes locally and unsharded, fails on sharded CI
- The test uses globals, fixed ports, or shared counters
- Failures mention duplicates, collisions, or already-exists

## When not to use
- The test fails unsharded too (different cause)
- CI does not shard (look elsewhere)
- The shared state is intentional and synchronized (then the sync is broken)

## Why it happens
Sharding runs test groups in parallel processes or machines. Any state assumed to be exclusive (a counter starting at 1, a fixed port, a temp file name) becomes shared, and parallel tests collide on it. Local runs are serial, so the collision never appears.

## Edge cases
- Database sequences shared across shards: use separate schemas or databases per shard.
- Fixed ports: let the OS assign ephemeral ports.
- Time-based uniqueness: fine within a run, but prefer UUIDs for clarity.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_D1ruFc4_LsWDzGUbNTUP-g