git pack: the push receipt marker requires a reflog write capability the vendor git on macOS does not advertise

[oceanwaves630]

The requirement

git.push writes its receipt marker with git reflog write refs/heads/<branch> <sha> <sha> khive-receipt:<id> (ADR-182 §Amendment 4 item 2). reflog write is a Git 2.51 subcommand. macOS ships Apple Git 2.50.1 as /usr/bin/git, so on a stock macOS every git.push refuses unsupported_toolchain before it does anything else, and #2470 records that this also makes every later refusal on that verb unobservable there.

A developer machine with only the vendor git cannot run the push verb at all. That is a large share of the platform the rest of the pack works on.

Why the subcommand was chosen

The marker has to record a receipt id against a branch without moving any ref, index or worktree. update-ref with identical old and new shas appends no reflog entry, so the obvious mechanism records nothing, which is what sent the design to reflog write.

Alternatives worth pricing before this is accepted as a hard floor

1. A dedicated ref namespace. refs/khive/receipts/<receipt-id> pointing at the pushed sha is an ordinary update-ref, works on every git in use, and is discoverable by for-each-ref. It moves a ref, but not one anybody reads as branch state, and git.reconcile would read it directly instead of parsing a reflog. Costs: the refs accumulate and need a retention rule, and they are pushed only if someone asks for that refspec.

2. A note. git notes --ref=khive-receipts attaches to the commit rather than the branch. Portable, but it writes an object and the mapping is commit-keyed, while the marker's question is branch-keyed.

3. Keep reflog write and make the floor explicit. Document the 2.51 minimum in the pack README and the git.push help, and have the remote suite state the requirement once rather than failing twelve arms (this is git pack: remote verbs need git 2.51+ (reflog write); tests should name the requirement #2470's ask). The verb then simply does not exist on a stock macOS.

Option 1 looks closest to the existing contract: git.reconcile already reconciles by reading a marker against a branch, and reading a ref is a stricter read than parsing reflog text.

Ask

A decision recorded in ADR-182 on whether the 2.51 floor stands. If it stands, say so in the ADR with the reason, because today the floor is a consequence of a mechanism choice rather than a stated requirement. If it does not, option 1 is a contained change: one writer, one reader, one retention rule.

[ohdearquant]

Correcting my own framing in the opening post, because it is wrong about the mechanism and the wrong version of it is the easier one to act on.

I wrote that the marker "pins a Git 2.51 floor". khive compares no version at all. local_git::push_marker_support runs git --version and git reflog -h, and the boolean it returns is help.stdout.contains("git reflog write "). perform_remote refuses unsupported_toolchain on that boolean and records the version string beside missing_capability on the receipt. So the guard keys on a capability, and 2.51 is only where upstream happens to have added it.

That distinction is load-bearing in both directions. A distribution can ship reflog write in a build numbered below 2.51, and a stripped build above it can lack the subcommand. A guard keyed on the number would be wrong on both, and the one khive has is not. The probe is right; I described it as something it is not.

What survives the correction is the whole of the ask. The vendor git on macOS does not advertise the capability, so git.push refuses before it does anything else on a stock machine, and the alternatives in the opening post are priced against that fact rather than against a version. Option 1, a ref under refs/khive/receipts/<id>, still buys the capability back on every git in use, and still replaces a reflog-text parse with a ref read.

Title edited to say capability rather than version. The body's "requires Git 2.51" sentence should be read as "requires a git whose reflog advertises write".

[ohdearquant]

Measured on a running daemon rather than argued from the platform, because the result is stronger than the issue assumed: the git that decides is the daemon's, and a daemon can resolve the vendor git even on a machine that has a newer one installed.

base_command in crates/khive-pack-git/src/local_git.rs does Command::new("git"), calls env_clear(), and re-exports only the daemon process's own PATH. So resolution is ordinary PATH order in whatever environment the daemon was started in, and nothing pins a binary.

On the daemon I measured, PATH lists /usr/bin at position 8 and the Homebrew prefix at position 17. Those are the only two directories on it containing an executable git. Walking the list in order and probing each with khive's own test, which is git reflog -h searched for the literal git reflog write :

resolved first: /usr/bin/git
  git version 2.50.1 (Apple Git-155)
  occurrences of "git reflog write " in reflog -h: 0

also present, later on PATH: 2.55.0
  occurrences: 1

So git.push through that daemon refuses unsupported_toolchain before it resolves a repository mapping, a credential or anything else, on a machine where a capable git is installed and on PATH, just not first. A developer would see the newer git from their own shell and the daemon would still refuse.

Two things follow that were not in the opening post.

The capability is not a property of the host, it is a property of the daemon's environment. A shell probe answers the wrong question. Anyone diagnosing this has to read the resolution the daemon would make, which today means reading its PATH from outside, because nothing on the verb surface reports it.

The toolchain fact is only observable by attempting a write. The version and the missing capability land on a git.push refusal receipt and nowhere else, so the only way to learn that pushes cannot work is to perform a push. git.gates is the read verb that already answers "what can this repository do here" — it reports the allowlist rows and the resolved target kind — and it is the natural place for the resolved git and the capability, so an operator can see the refusal coming instead of discovering it. That is a small addition and I would take it as part of whichever way this issue is decided.

The decision in the opening post is unchanged and this makes it sharper: option 1, a ref under refs/khive/receipts/<id>, removes the dependency entirely rather than documenting a requirement that a correctly-installed machine can still fail to meet.