pre-push notes mirror reports ETIMEDOUT as a failure line when the push itself succeeded

[MongLong0214]

Second observation from real use of v0.8.2 on MongLong0214/agent-control-plane. This one is minor and the behaviour is arguably correct — filing it for the wording and the retry story, not the fallback.

What happened

$ git push -q origin main
commitlore: notes mirror (origin) failed: spawnSync git ETIMEDOUT; branch push continues

The branch push succeeded. Immediately afterwards:

$ commitlore sync
origin       nothing-to-do  no notes mirror on either side

So the mirror had nothing to publish in the first place, and the failure line was about a transient network timeout while checking.

What is right about it

Not blocking the push is the correct call, and saying so on the same line (branch push continues) is genuinely useful — I did not have to guess whether my push landed.

The friction

The line reads as though something was lost. In this case nothing was: there were no notes to mirror at all. An agent reading that output has to run commitlore sync to find out whether it needs to do anything, and a human is likely to either ignore it permanently or chase it.

Two small things would fix it:

1. Distinguish "could not reach the remote" from "failed to publish notes I had." If the local mirror is empty, the message could say so — notes mirror unreachable (nothing pending); branch push continues is not alarming and is still honest.
2. Say what to do. run 'commitlore sync' to retry turns it into an actionable line. Retrying worked immediately here.

If a later push would republish pending notes anyway, saying that explicitly would be even better, since then the line needs no action at all.

Reproduction

Hard to force deterministically — it needs the remote to time out during the pre-push hook. It reproduced once here under host load (the machine was at load ~45 from concurrent builds), which suggests the hook's git invocation may be more timeout-sensitive than the push itself. If the hook uses a shorter timeout than git's own defaults, raising it or retrying once would make this rarer.

Environment

commitlore 0.8.2 · macOS (Darwin 25.3.0) · Node 22 · git push -q origin main under heavy host load

[MongLong0214]

Second field reproduction, different repository and different operator — this one on MongLong0214/commitlore itself, twice in a row on consecutive pushes:

commitlore: notes mirror (origin) failed: spawnSync git ETIMEDOUT; branch push continues

That makes it reproducible across two repositories and two machines rather than a one-off network blip, so the wording is worth fixing rather than waiting to see if it recurs.

What the line still does not answer

The fail-open is correct and is not in question. What a person needs next is:

1. Is there a local note waiting? The mirror may hold a record that never reached the remote. Nothing here says whether local state diverged from the remote.
2. Will the next push retry it? If yes, the line should say so and the operator does nothing. If no, this is a silent gap that widens with every push.
3. If not automatic, what command settles it? The message names no action.

Right now the operator's only rational move is to guess, and the guess that costs least — do nothing — is also the one that quietly loses records if the answer to (2) is no.

Suggested shape

State the outcome and the next step, not just the failure:

commitlore: notes mirror (origin) did not sync: git timed out after <n>s.
  N record(s) are held locally and were not published.
  The next push retries automatically.        # or: run  to publish them
  Your branch push completed.

Whether line 3 says "retries automatically" or names a command is a product decision this issue should settle, because the correct operator behaviour differs completely between the two.

Moved to R1 · Operational Boundary: this is the observability boundary rather than a defect in the sync itself.