Pin the Clock Before You Merge an Agent Patch

Description and use

An agent patch used a naive datetime.now, causing billing errors. A freeze layer with pytest fixtures was added to provide deterministic, timezone‑aware time, preventing future mistakes.

Problem

Agent patches that use the system clock without timezone awareness can cause incorrect billing when daylight saving changes or different environments have different timezones.

Outcome

The patch now deterministically calculates billing windows regardless of environment timezone or daylight saving changes, preventing future billing errors.

Workflow

• Identify all calls to datetime.now, time.time, random, uuid4, os.listdir, locale.setlocale, and bare open in the codebase.
• Create a short seam log documenting these hits for human review.
• Define a Clock protocol and a SystemUtcClock implementation that returns timezone-aware UTC time.
• Add a FrozenClock fixture that reads ISO timestamps from a committed JSON fixture file.
• Replace calls to datetime.now in the helper with clock.now() and validate tzinfo is present.
• Add unit tests that use the FrozenClock fixture to assert deterministic window IDs.
• Ensure the fixture JSON contains required fields (id, iso, window) and is committed as data only.
• Review and approve the seam log and fixture changes before merging the agent patch.

Evidence

The helper called datetime.now with no timezone. The agent's sandbox lived entirely in UTC. The production batch box lived in US/Eastern.

Source

The suite must freeze every world the patch can see. Humans own that freeze for the life of the repo.

Source