repo checkout --ref Only Sees Real origin, Not a Local-Only Branch Push

Applies to: Anyone relying on multica repo checkout <url> --ref <branch> to pick up work from a prior agent hop on the same branch.

The trap

multica repo checkout --ref <branch> builds its worktree from the daemon's bare-clone cache, resolving --ref through refs/remotes/origin/<branch> only. It does not read a same-named local-only branch ref in that cache — even one an agent pushed directly into the cache's local refs, not to GitHub.

Until a branch reaches the real GitHub origin, the next agent to run multica repo checkout --ref <branch> will not see the prior agent's commits. repo checkout --help's own wording reads like the bare-clone cache is durable and checkout-visible in general — it is, for anything already fetched from origin, but not for a ref that only exists locally in that cache.

This bites any multi-hop branch: a second agent picking up work after a first agent's session ends, before anyone has pushed to GitHub.

The rule

The agent finishing a hop pushes the WIP branch to real origin at the end of its session — that push, not the local commit, is what makes the branch visible to the next hop's checkout.

In the Enkidu crew chain, this means:

• Codi and Desi push their branch to origin after committing, at the end of their session — not before, since intermediate commits within one session don't need to cross the checkout boundary.
• Riley's job starts after the branch is already on origin. She confirms it's there before opening the PR, and pushes only as a fallback if the finishing agent's push is missing. PR-open, CI-watch, and rebase hygiene are still hers.

See docs/guides/multica-agent-crew.md for the full crew instructions this convention lives in.

Why not fix it at the platform level instead

The alternative — have multica repo checkout --ref <branch> also consult a same-named local branch in the bare cache — is a daemon/CLI behavior change outside this app repo. Given a choice between that platform change and this process change, Josh approved the process change (this convention) as the fix, since it's actionable entirely within agent instructions and doesn't require a daemon release.

Symptom if you hit this anyway

A hop's "done" comment reports commits on a branch, but the next agent's multica repo checkout --ref <branch> produces a worktree without those commits — the branch looks unchanged from before that hop ran. If a chain has multiple hops before the first real push to origin (e.g. Codi → Dori landing docs on the same branch, or a second Codi pass before Riley opens a PR), each intermediate hop's work can look silently lost to the next one.

Related

• OBJ-1241 (this decision) — surfaced by Dave while diagnosing OBJ-1229, where two hops' worth of "done" reports were invisible to the next agent for exactly this reason.
• shared-mirror-remote-pollution-gotcha.md — sibling gotcha, same shared-mirror surface, hit from the remote-pollution side instead of the "checkout can't see a local-only branch" side.
• docs/guides/multica-agent-crew.md — the crew instructions that implement this convention (Codi, Desi, Riley sections).

---

Last updated: 2026-08-12 (OBJ-2477: added a reciprocal Related link to the new shared-mirror-remote-pollution-gotcha.md)

Previously: 2026-07-09 (OBJ-1241: document the origin-only checkout gotcha and the branch-push convention that closes it)