Dispatch Base

Step 3 — Otherwise, leave the checkout alone and report

When the base cannot be brought up to date, do not touch the checkout. Three of the four cases below are precondition failures and the fourth is the merge itself refusing. Say which one it was, with the distance from origin/main, in these terms:

• Tracked changes present: name the files. They are invisible to the units either way: a unit's copy is made from the last commit (docs/dispatcher-mode.md), so uncommitted work never reaches one. Committing or stashing is the user's to do, not yours. Untracked files are deliberately not a blocker, which is why --untracked-files=no is in step 1: a fast-forward that would clobber one fails cleanly by itself, and counting them would refuse on nearly every real checkout.
• HEAD is not main: every unit is cut from that branch and carries its unmerged work into every PR the batch produces. Name the branch and its distance from origin/main. This is the sharpest of the four, because nothing about it looks wrong: a feature branch dispatches exactly as smoothly as main does. It is the 2026-10-10 case above.
• HEAD is ahead of origin/main: there is nothing to fast-forward to, and the commits that put it ahead are inherited by every unit's branch and turn up in every unit's PR. Report the count; pushing or moving is the user's call.
• The merge command itself fails although every precondition passed: a fast-forward that would clobber a file origin/main newly tracks is the concrete case. Report the git error and do not dispatch. Decide on the exit status, never on the output: git writes Updating <old>..<new> to stdout and the refusal to stderr, so captured output of a refusal can end in that line, after Aborting, reading exactly like a successful fast-forward. --ff-only never partially applies, so the checkout is unchanged and there is nothing to undo.

git log --oneline HEAD..origin/main names the commits behind the count, which makes a refusal something the user can act on rather than a number.

The next move is the user's, and there are three legitimate ones: dispatch anyway onto the older base, clear the blocker and dispatch after it, or defer the batch. Take their answer rather than picking one, and never clear the blocker on their behalf: committing, stashing or switching branch is the local work this step refuses to touch. If they clear it, run step 1 again before dispatching. Ad hoc, put the refusal to them before the first dispatch. A queue skill says where it carries the refusal instead, usually to the moment it asks how many units to dispatch, because its selection works from origin/main and does not depend on the checkout.

Step 4 — After dispatch, read the base dispatch reports

dispatch's success line ends with the base it cut the worktree from (resolve_dispatch_base in src/dispatch.rs):

dispatch: spawned isolated agent for '<name>' in <dir>, cut from main at c701932

Read that clause on every dispatch, and compare its sha with origin/main:

git rev-list --left-right --count <sha>...origin/main  # "0  0" is origin/main itself

Treat any of these as a finding to report, not as noise:

• a branch other than main, or detached HEAD at <sha>;
• a sha that is not origin/main, unless the user chose to dispatch onto an older base after a step 3 refusal, in which case report the distance they chose;
• no clause at all: that is an older build, or a probe of HEAD that failed, in which case dispatch cut the worktree from HEAD without naming it. It is never a base that is fine. Fall back to the branch's own record below, and say the clause was missing.

When the clause is missing, read the commit the unit's branch was created at from its first reflog entry, which later commits in the unit do not change. Take the branch from the worktree the success line names rather than from the name you passed: dispatch sanitizes the name before it builds the branch, so fix auth becomes agent/dispatch-fix-auth. Read it right after the dispatch, before the unit has had time to switch branch:

branch=$(git -C "<dir>" rev-parse --abbrev-ref HEAD)            # <dir> from the success line, quoted
git reflog show --format='%h %gs' "$branch" | tail -1          # "<sha> branch: Created from <...>"

Use that sha only when the subject starts branch: Created from. It reads Created from HEAD when dispatch cut the worktree with no start-point, which is what a missing clause means, and Created from <full sha> when it passed the sha it reported. An empty result or any other subject means the reflog cannot answer, because it is disabled, expired or was rewritten. Then say the base could not be verified, and do not report a sha.

On a build older than the fix for issue #1643, the clause was a probe of HEAD read just before a git worktree add that read HEAD again, so the two could differ if HEAD moved in between; the reflog sha is the base there. A current build cuts the worktree from the sha it reports, so the clause is the base.

Catching it here costs one stopped unit, before the unit has spent any time working from the wrong tree.

Report the base as a distance from origin/main

Wherever the dispatching skill or the ad-hoc reply says where the work went, give the base as the sha plus 0 behind (after step 2 fast-forwarded it, or when it was already current) or N behind (when step 3 declined to move it), measured at the moment of dispatch. Quote dispatch's own cut from … at <sha> clause rather than recomputing it. Report it when the base was current too: nothing else tells a base that was checked from one nobody looked at, and "cut from main" reads identically whether main is level with the remote or six commits behind it.