7.9 KiB
Push check in the repository, with reviewed binaries
Written 2026-10-24 by Sage for Mos's mos-1572 ("Go with A for the guard"), after rows 265 and 310 raised the binary question (mos-1570, sage-3978).
Brief: push-check.sh passes a binary only when the reviewed candidate lists its path and sha256
Why. The lead's push check is a scratch script, /mnt/storage/scratch/sage-r64/pushcheck.sh
(mos-0856/0857), so nobody has reviewed it and no test covers it. Its NO_BINARY step refuses any
path that git diff --numstat BASE SHA reports as binary (- in the first column). Row 265 had to
waive that step by hand for 22 gzip logs. Row 310 (W2) will need committed WASM, fonts and test blobs.
Mos chose option A: keep the binary check, and let a binary through only when its path and sha256
appear in the candidate a reviewer approved. Whether any large binary lands at all is a separate
question for Jason (Vikunja 618). This row builds the guard, not that answer.
Read first.
- The scratch script, copied under "The scratch script today" at the end of this brief. Don't read
/mnt/storage/scratch/sage-r64itself; it's Sage's scratch. packages/queue/README.md, sections onmove ID in-review(manifest and commit candidates) andreview verify-commit.packages/queue/src/review.mjsfor how a round's candidate and its receipts are stored. Runningscripts/mosaic queue show Nprints them.docs/plans/2026-10-20_force-push-guard.md, row 211 (Darkwing, in progress). That row ownsscripts/git-hooks/pre-push, the hook install andscripts/slot-busy.sh. Don't touch those files, and don't wire this check into a hook.
What ships.
scripts/push-check.sh SHA EXPECTED_LOG [--row N]...(new). It runs the scratch script's steps in the same order and prints the same tokens, so the lead's push sequence only changes its path:LOG_OK,FF_OK,NO_BINARYorBINARY_REVIEWED <n>,SECRETS_CLEAN,NO_ATTRIBUTION, thenPUSH_READY BASE..SHAas the last line. Every refusal prints oneSTOP <reason>line and exits 1. A usage or environment error exits 2. It works in the repository the caller's cwd is in. The base ref defaults torefs/remotes/origin/refactor, and--base-ref REFoverrides it for tests. A fetch happens only when--fetchis given, and the lead's sequence passes it.- The binary step. For each path that
git diff --numstat BASE SHAmarks binary and that exists at SHA (a deleted binary needs no review):- compute the sha256 of the blob at
SHA:path(git cat-file blob, not the working tree); - look for an approved candidate among the
--rowrows. A round counts only when it is the row's latest round and has a receipt with verdictapprovewhose candidate equals that round's candidate. Achangesreceipt in the same round blocks it; - for a manifest candidate, the manifest must hold the line
<sha256> <path>exactly; - for a commit candidate, use the same rule as
queue review verify-commit. The path must be one the candidate changed from its first parent, and the sha256 of the candidate's blob must equal SHA's; - no match prints
STOP binary <path> <sha256> not in a reviewed candidate. With no--row, any binary stops, which is today's behaviour. Read the queue only throughscripts/mosaic queue show Nor the queue package's read functions. Never write the queue or post anything.
- compute the sha256 of the blob at
- The secret scan and the attribution check stay as they are. A binary passes the secret scan only through the review above. Decompressing gzip to scan it is a separate row if anyone wants it (mos-1570). Don't add it here.
scripts/test-push-check.sh(new), run bytimeout -k 10like the other suites. It builds a scratch bare remote, a scratch clone and a scratch queue. It never touches origin, the canonicaldocs/plans/queue.jsonor a seat's queue lock. If the queue CLI can't read a scratch queue without a full scratch copy of the repository, use a scratch copy. If that is impractical too, stop and ask Sage before inventing a test-only override. Cases:- a text-only range prints
NO_BINARYandPUSH_READY; - an unlisted binary stops, naming the path;
- a listed path with a different sha256 stops;
- an approved manifest candidate passes and prints
BINARY_REVIEWED 1; - an approved commit candidate passes. One whose blob for that path differs from SHA's stops;
- a round with a
changesreceipt, a superseded earlier round, and an approve receipt for a different candidate each stop; - a deleted binary passes with no
--row; - a non-fast-forward SHA, a log mismatch, an attribution line and a planted fake secret each stop, and nothing after the stop prints;
- the last line is
PUSH_READYonly on success, so| tail -1 | grep -q '^PUSH_READY 'is safe.
- a text-only range prints
- Mutants, each killed by the test: skip the sha256 comparison; accept a
changesround; accept an earlier round; read the working tree instead of the blob; let a binary through when--rowis absent. docs/TOOLS.md: one entry forpush-check.shwith usage, the tokens and the exit codes.
Files owned. scripts/push-check.sh, scripts/test-push-check.sh, the new docs/TOOLS.md entry,
and your agents/<seat>/work/queue-<row>/ packet (BUILD.md, plain-text evidence). Anything else needs a
brief amendment.
Out of scope. The pre-push hook and slot check (row 211). Deciding whether W2's WASM or W1's data lands (Jason, Vikunja 618). Gzip scanning. Retiring the scratch script, which Sage does after landing.
Gate. A separate Codex thread does the first review. Dewey reviews once on the landing candidate
(guards go to a Claude reviewer, mos-1542). scripts/test-push-check.sh and every other
scripts/test-*.sh are green on Sage's landing gate, and the mutants are killed. Done when Sage's next
push runs through scripts/push-check.sh instead of the scratch script. Evidence is plain text
(BRIEF-TEMPLATE, mos-1570). Use a TMPDIR from mktemp -d /mnt/storage/scratch/tmp/XXXXXX.
The scratch script today
#!/bin/bash
# Push checks for an explicit sha (mos-0856/0857). Usage: pushcheck.sh SHA EXPECTED_LIST_FILE
# EXPECTED_LIST_FILE holds the exact `git log --oneline origin/refactor..SHA` lines, newest first.
set -o pipefail
cd /mnt/storage/src/mosaic-stack || exit 9
SHA=$(git rev-parse --verify "$1^{commit}") || { echo "STOP sha"; exit 9; }
git fetch -q origin || { echo "STOP fetch"; exit 9; }
BASE=$(git rev-parse refs/remotes/origin/refactor) || exit 9
diff <(git log --oneline "$BASE..$SHA") "$2" && echo LOG_OK || { echo "STOP log"; exit 1; }
git merge-base --is-ancestor "$BASE" "$SHA" && echo FF_OK || { echo "STOP ff"; exit 1; }
[ "$(git diff --numstat "$BASE" "$SHA" | awk '$1=="-"' | wc -l)" = 0 ] && echo NO_BINARY || { echo "STOP binary"; exit 1; }
if git diff "$BASE" "$SHA" | grep -E '^\+' | grep -iqE 'BEGIN [A-Z ]*PRIVATE KEY|ghp_[A-Za-z0-9]{20}|sk-ant-[A-Za-z0-9-]{10}|xox[bp]-|AKIA[0-9A-Z]{16}|(token|secret|password)["'"'"' ]*[:=] *["'"'"'][A-Za-z0-9_\-]{24,}'; then echo "STOP secrets"; exit 1; fi
echo SECRETS_CLEAN
if git log --format=%B "$BASE..$SHA" | grep -iqE 'co-authored-by|generated with'; then echo "STOP attribution"; exit 1; fi
echo NO_ATTRIBUTION
echo "PUSH_READY $BASE..$SHA"
Amendment 1 (Dewey's landing review, dewey-0955)
git diff --numstat follows git attributes, so a diff attribute (from the tree's .gitattributes,
.git/info/attributes or core.attributesFile) can make a binary blob count as text. Item 2 changes.
A path is binary when numstat marks it binary, or when it exists at SHA and its blob (git cat-file blob SHA:path) has a NUL byte in its first 8000 bytes, git's own rule. Attributes can add binaries
but never remove them. Tests add scratch cases for each of the three attribute sources, each with no
--row and each expecting STOP binary. A sixth mutant drops the NUL scan. Also, when the queue read
returns code 0 with an unconfirmed-tail note, the check stops (fail closed), with a test.