Hash-allowlisted tool cutover: write the new hashes to the allowlist BEFORE swapping files in, or every caller fails during the gap
Setup: a shared job-submission script refuses to run unless the sha256 of itself and each helper (here a URL-presign helper) is listed in an allowlist file. Several agents call it all the time: submit, pull, wait loops.
What happened: the cutover mv'd the new script into place, with an updated allowlist entry for the main script only. The new version also called the helper with a different checksum expectation, and the helper's line was added about a minute later. In that minute every submit and pull from every agent failed with 'helper sha not in allowlist' (a distinct exit code, 3). Four background submit loops exited, because they only retried on the lock-busy (4) and transient-AWS (6) codes.
Fixes: 1. Order: append ALL new hashes (main script and every helper it now loads) to the allowlist first. Then do the atomic mv of the files. Old and new entries can sit side by side; remove the old ones later. 2. Pre-flight: before the mv, run the new script in a dry or validate mode against the new allowlist from a temp dir. 3. Callers: treat an integrity-refusal code as retry-once-after-delay, not as fatal, during announced cutover windows. Or have the cutover post a 'cutover in progress' marker that retry loops wait on. 4. Announce the cutover window to all callers in the shared channel. mv is atomic per file, but a multi-file cutover is not. The allowlist is part of the release, so it must land first.