Agent Config Drifts Quietly Across Environments: Detection and Correction

Reconcile by hashing after normalization

The core is simple: normalize the shared config, hash it, and compare across environments. Normalization is there so that mere differences in key order or indentation don't get flagged as different. Parse the TOML or JSON once, sort the keys, write it back out, then hash.

import hashlib, json, tomllib
 
SHARED_KEYS = {"model", "timeout_s", "max_retries", "gate_thresholds"}
 
def shared_fingerprint(config_path: str) -> str:
    with open(config_path, "rb") as f:
        data = tomllib.load(f)
    # Pull only shared keys, normalize order, then hash
    shared = {k: data[k] for k in sorted(SHARED_KEYS) if k in data}
    canonical = json.dumps(shared, sort_keys=True, ensure_ascii=False)
    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:16]

Print this fingerprint in each environment and compare it to the source of truth's. Match means shared config is aligned. On mismatch, show exactly which keys diverged, as below. The hash quickly decides "is it drifted," and the diff shows "where it drifted" — a clean division of labor.

def diff_shared(a_path: str, b_path: str) -> list[str]:
    def load(p):
        with open(p, "rb") as f:
            d = tomllib.load(f)
        return {k: d.get(k) for k in SHARED_KEYS}
    a, b = load(a_path), load(b_path)
    return [f"{k}: {a[k]!r} != {b[k]!r}" for k in SHARED_KEYS if a[k] != b[k]]

Handle drift in three tiers

Detecting it doesn't mean every case should be fixed immediately. I handle drift in three tiers.

First is harmless drift. Environment-specific differences like parallelism or local paths are excluded from reconciliation, so they never appear here. If one does appear, it's a sign your split is wrong, so revisit SHARED_KEYS.

Second is warn drift. Values like timeout or retry cap — not fatal when diverged, but eventually one side behaves differently. On detection, raise a warning and align them during your next bit of work. Don't auto-fix; let a human decide which way to align.

Third is fix-now drift. Values like model name or gate thresholds, which tie directly to output quality or safety. Halt the job the moment it's detected and force-align it to the source of truth. In my operation, I once found one environment with a drifted gate threshold, and an article that had skipped the quality check was about to ship — ever since, this tier alone is auto-corrected.

CRITICAL = {"model", "gate_thresholds"}
 
def decide(diff_keys: set[str]) -> str:
    if diff_keys & CRITICAL:
        return "halt_and_fix"   # fix now: stop the job, align to source of truth
    if diff_keys:
        return "warn"           # warn: a human aligns it
    return "ok"

Build a weekly reconciliation into operations

Detection machinery earns its keep only when run on a cadence. Once a week, in a quiet Sunday slot, I run a reconciliation that checks every environment's fingerprint against the source of truth. No diff prints a single "match" line, so the check takes seconds.

One trick for timing: right after a big tool update, I run an extra reconciliation. Tools like Antigravity, whose versions move briskly, can change defaults on update, and that's exactly when drift slips in. Adding "right after an update" to the regular weekly cadence catches default-change divergence far sooner.

It's far easier to set up the ability to notice drift than to fix it after the fact. Fix the source of truth in one place, reconcile only shared config by hash, and auto-correct only the high-impact values — this three-part stance makes agents across environments remarkably quiet. Start by printing and comparing the shared-key fingerprint across your two environments. I hope it helps anyone puzzling over the same "only one side fails" mystery.