On June 27, a close guard rejected a legitimate item because it had found the wrong bundle.
We filed the problem during a 5-hour, 58-minute build session. The guard had one useful job before an automated close: stop the close if the artifact bundle was stale. Instead it reported a match for a bundle that was not attached to the item being closed.
The first read looked like a normal safety intervention. A guard found a stale artifact and stopped an irreversible state change, which is what it was there to do. But the item had a current bundle, and the result did not line up with the files in front of us. The alert was specific enough to be believable and wrong enough to matter.
The comparison that threw away the identity
The guard compared bare filenames. It never compared bundle paths.
That distinction is small in code and absolute in a filesystem. Two artifacts can share a filename while belonging to different work paths. Once the guard discarded the directory, it no longer knew which artifact it had found. It only knew that a file with the same label existed somewhere in the candidate set.
The failure reduced to this shape:
expected_key = filename(expected_bundle_path)candidate_key = filename(candidate_bundle_path)
if expected_key == candidate_key: block_close_as_stale()That comparison is valid only if a filename is globally unique, and ours was not. A same-named bundle from another path could block the close even though the intended bundle was current and complete.
We worked backward from the result and did not take the guard’s word for it. First we checked the bundle the item actually referenced. Then we checked the candidate that had satisfied the guard. The paths were different. The collision appeared only after both had been flattened to the last path segment.
Nothing was stale. The guard had turned a path identity problem into a filename equality problem.
Why the obvious fixes lost
Removing the guard would have made the false positive disappear. It would also have reopened the original failure mode, where an automated close proceeds with a stale artifact bundle. That fixes nothing.
Keeping the filename check and adding a timestamp check was not enough either. Timestamps can tell you whether an artifact is old. They cannot tell you whether the artifact belongs to this item. A fresh bundle in the wrong directory is still the wrong bundle.
The durable key is the path, with whatever normalization the artifact store requires before comparison. The corrected shape is deliberately boring:
expected_key = canonical_path(expected_bundle_path)candidate_key = canonical_path(candidate_bundle_path)
if expected_key == candidate_key: evaluate_staleness()The ordering matters. Identity comes first, and staleness is a property of the artifact once it has been identified.
We shipped the path-aware bundle guard correction on July 13 alongside related guard work and verified it live. The code change was short. The test that matters is the one that asks whether two bundles with the same filename in different paths can coexist without one blocking the other item’s close.
A guard is still a decision system
This class of bug does not crash. The automated close simply does not happen, and the guard supplies a plausible explanation. That makes false positives expensive. They pile up as manual retries and exceptions, and as distrust in the automation that was meant to remove that work.
We want a guard that blocks a transition to be easy to interrogate. It should show the full identity it compared, and a shortened label that merely looks distinctive does not count. If a guard cannot tell us which exact artifact made it stop the workflow, it has not earned the authority to stop it.
A guard that matches on a compact key such as a bare filename can block legitimate work because of a same-named item elsewhere, and it will give a reasonable-sounding reason when it does. If the block shows the full identity it compared, you can tell in minutes whether it is real.