Ha, and of course just messing around gets me something that actually works.

There always seems to be just one more stackoverflow thread to read that has the real answer: https://stackoverflow.com/questions/68435607/how-to-clone-ma... (found via Kagi which I wasn't using before, and the search "pygit2 detached head")

    def checkout_branch(path, branch_name):
        repo = pygit2.Repository(path)

        main_branch = repo.lookup_branch("main")
        print(f"Main branch upstream: {main_branch.upstream_name}")

        if branch_name not in repo.branches.local:
            print(f"Branch {branch_name} not found in local branches")
            remote_branch = "origin/" + branch_name
            if remote_branch not in repo.branches.remote:
                raise SystemExit(f"Branch {remote_branch} not found in remote branches")
            (commit, remote_ref) = repo.resolve_refish(remote_branch)
            repo.create_reference("refs/heads/" + branch_name, commit.hex)

        branch = repo.lookup_branch(branch_name)
        print(f"Branch name: {branch.name}")

        repo.checkout(branch)
        print(f"Is branch head? {branch.is_head()}")

        (commit, branch_remote) = repo.resolve_refish("origin/" + branch_name)
        print(f"Remote branch: {branch_remote.name}")
        branch.upstream = branch_remote

With git reflog telling me the right thing:

    d44aedc (HEAD -> test, origin/test) HEAD@{0}: checkout: moving from main to test

And git push has the remote branch already set.

I wish there was a pair programmer AI that you had to explain stuff to. That would enable the "by explaining it, I solved it" phenomenon.