Fetch origin and cut agent branches from origin/HEAD at spawn

Agents spawned by handler were getting branches several commits behind
main. Two compounding causes: sync_project ran 'git pull --ff-only' in
the project root, which only moves whichever branch the root checkout
happens to be on — an agent parked on a feature branch left origin/*
stale (and the pull's 'no tracking information' failure degraded to an
easy-to-miss sync_note). Then worktree spawns cut new branches from the
root's HEAD, inheriting that stale state.

sync_project now fetches origin (refreshing origin/* regardless of the
checkout), re-pins origin/HEAD, and fast-forwards the checkout only when
it sits on the default branch — a diverged default branch still fails
loudly. New worktree branches are cut from origin/HEAD with --no-track
so they start at the remote default branch's tip and don't adopt it as
upstream.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V7mF6qeryi9nJthaxYkfPm

src/handler/control/gitops.py

@@ -114,6 +114,34 @@ def clone(
     return _run(args, cwd=None, env=env, timeout=_NETWORK_TIMEOUT)
 
 
-def pull_ff(cwd: str, env: dict[str, str] | None = None) -> tuple[bool, str]:
-    """Fast-forward-only pull — never merges, so a diverged clone fails loudly."""
-    return _run(["pull", "--ff-only"], cwd, env=env, timeout=_NETWORK_TIMEOUT)
+def fetch(cwd: str, env: dict[str, str] | None = None) -> tuple[bool, str]:
+    """``git fetch origin`` — refreshes every ``origin/*`` ref.
+
+    Unlike a plain pull, this works no matter which branch the working tree has
+    checked out (or left parked), so the remote's state is always current locally.
+    """
+    return _run(["fetch", "origin"], cwd, env=env, timeout=_NETWORK_TIMEOUT)
+
+
+def set_default_head(cwd: str, env: dict[str, str] | None = None) -> tuple[bool, str]:
+    """``git remote set-head origin --auto`` — (re)pin ``origin/HEAD``.
+
+    ``origin/HEAD`` is how the remote's default branch is known locally; clones made
+    by older tooling can lack it, and the remote's default can change.
+    """
+    return _run(["remote", "set-head", "origin", "--auto"], cwd, env=env,
+                timeout=_NETWORK_TIMEOUT)
+
+
+def default_branch_ref(cwd: str) -> str | None:
+    """The remote default branch as a local ref name (``origin/main``), or ``None``."""
+    ok, out = _run(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], cwd)
+    if not ok or not out:
+        return None
+    return out.removeprefix("refs/remotes/") or None
+
+
+def merge_ff(cwd: str, ref: str) -> tuple[bool, str]:
+    """Fast-forward-only merge of ``ref`` — never merges, so a diverged checkout
+    fails loudly instead of silently growing a merge commit."""
+    return _run(["merge", "--ff-only", ref], cwd)

src/handler/control/reposync.py

@@ -1,4 +1,4 @@
-"""Clone-or-pull a project's repository — the stateless "always pull" step.
+"""Clone-or-fetch a project's repository — the stateless "always pull" step.
 
 Where a clone lands on disk is Handler's concern, not the operator's: the API computes
 ``root_dir`` under ``PROJECTS_ROOT`` at registration, and this module makes the checkout
@@ -70,11 +70,16 @@ def ssh_env(git_remote: str | None, conn: Connection) -> dict[str, str]:
 
 
 def sync_project(project: dict, conn: Connection | None = None) -> dict:
-    """Clone the project's remote into ``root_dir``, or fast-forward an existing clone.
+    """Clone the project's remote into ``root_dir``, or refresh an existing clone.
 
     Idempotent by design — scheduled/stateless runs call this before every spawn so the
-    working tree always starts from the remote's latest state. Raises :class:`SyncError`
-    when the project has no remote or git fails.
+    working tree always starts from the remote's latest state. An existing clone is
+    ``git fetch``\\ ed rather than pulled: a pull only moves the branch the root happens
+    to have checked out, and an agent parked on a feature branch used to leave
+    ``origin/*`` (and therefore every branch cut for a new agent) hours stale. After
+    the fetch, ``origin/HEAD`` is re-pinned and the checkout is fast-forwarded only
+    when it is sitting on the default branch. Raises :class:`SyncError` when the
+    project has no remote or git fails.
     """
     remote = project.get("git_remote")
     root = project["root_dir"]
@@ -88,10 +93,22 @@ def sync_project(project: dict, conn: Connection | None = None) -> dict:
         env, config = _auth_context(project, conn)
 
     if gitops.is_repo(root):
-        ok, out = gitops.pull_ff(root, env=env)
+        ok, out = gitops.fetch(root, env=env)
         if not ok:
-            raise SyncError(f"pull failed in {root}: {out}")
-        return {"action": "pulled", "root_dir": root, "detail": out}
+            raise SyncError(f"fetch failed in {root}: {out}")
+        # Best-effort: worktree spawns cut new branches from origin/HEAD, so keep it
+        # pinned even for clones that predate it (or whose remote default changed).
+        gitops.set_default_head(root, env=env)
+        detail = out
+        default_ref = gitops.default_branch_ref(root)
+        if default_ref and gitops.current_branch(root) == default_ref.split("/", 1)[1]:
+            ok, ff_out = gitops.merge_ff(root, default_ref)
+            if not ok:
+                raise SyncError(
+                    f"fast-forward of {default_ref} failed in {root}: {ff_out}"
+                )
+            detail = ff_out or detail
+        return {"action": "pulled", "root_dir": root, "detail": detail}
 
     os.makedirs(os.path.dirname(root) or ".", exist_ok=True)
     ok, out = gitops.clone(remote, root, env=env, config=config)

src/handler/control/spawn.py

@@ -95,10 +95,12 @@ def spawn(
             raise SpawnError(f"agent '{name}' already exists in project '{project_id}'")
 
         # Stateless workflows: start every run from the remote's latest state. An
-        # existing clone is fast-forwarded (failure degrades to a note — a stale tree is
-        # usable, an offline forge shouldn't brick spawning); a missing/empty root is
-        # cloned, and that failing is fatal (there is nothing to run against). A
-        # non-empty root that isn't a git repo is left alone — it's manually managed.
+        # existing clone is fetched — refreshing origin/* even when the root checkout is
+        # parked on an agent's branch — and fast-forwarded when it sits on the default
+        # branch (failure degrades to a note — a stale tree is usable, an offline forge
+        # shouldn't brick spawning); a missing/empty root is cloned, and that failing is
+        # fatal (there is nothing to run against). A non-empty root that isn't a git
+        # repo is left alone — it's manually managed.
         root = project["root_dir"]
         if project.get("git_remote"):
             if gitops.is_repo(root):

src/handler/control/worktree.py

@@ -35,6 +35,25 @@ def _slug(name: str) -> str:
     return slug or "agent"
 
 
+def _default_branch_start(project_root: str) -> str | None:
+    """The remote default branch ref (``origin/main``) when the clone knows it.
+
+    New agent branches are cut from here rather than the root's ``HEAD``: the root
+    checkout can legitimately be parked on some earlier agent's branch, and cutting
+    from it handed fresh agents history that was hours behind the remote.
+    """
+    result = subprocess.run(
+        ["git", "-C", project_root, "symbolic-ref", "--quiet",
+         "refs/remotes/origin/HEAD"],
+        capture_output=True,
+        text=True,
+    )
+    ref = result.stdout.strip()
+    if result.returncode != 0 or not ref.startswith("refs/remotes/"):
+        return None
+    return ref.removeprefix("refs/remotes/")
+
+
 def _branch_exists(project_root: str, branch: str) -> bool:
     return (
         subprocess.run(
@@ -69,13 +88,21 @@ def resolve_working_dir(
             raise IsolationError(f"{target} escapes project root {project_root}")
         # `git worktree add <path> <branch>` only checks out an *existing* ref; a fresh
         # feature branch won't exist yet (spawn starts from the remote's latest state), so
-        # create it with -b. An existing local branch is checked out as-is; if it exists
-        # only on a remote, git DWIMs a tracking branch from the bare `add`.
+        # create it with -b — from origin/HEAD when the clone has a remote, so the new
+        # branch starts at the remote default branch's tip regardless of where the root
+        # checkout is parked (--no-track: the branch must not adopt the default branch as
+        # its upstream, or the agent's plain `git push` would aim at it). An existing
+        # local branch is checked out as-is; if it exists only on a remote, git DWIMs a
+        # tracking branch from the bare `add`.
         cmd = ["git", "-C", project_root, "worktree", "add"]
         if _branch_exists(project_root, worktree_branch):
             cmd += [target, worktree_branch]
         else:
-            cmd += ["-b", worktree_branch, target]
+            start = _default_branch_start(project_root)
+            if start:
+                cmd += ["--no-track", "-b", worktree_branch, target, start]
+            else:
+                cmd += ["-b", worktree_branch, target]
         result = subprocess.run(cmd, capture_output=True, text=True)
         if result.returncode != 0:
             raise WorktreeError(

tests/test_project_from_server.py

@@ -150,7 +150,7 @@ def test_sync_endpoint_400_without_remote(client, auth, env, tmp_path):
 @pytest.fixture
 def fake_sync_gitops(monkeypatch):
     """Fake the clone/pull side of the gitops seam."""
-    state = {"clone": [], "pull": [], "config": [], "repos": set(), "ok": True, "out": ""}
+    state = {"clone": [], "fetch": [], "config": [], "repos": set(), "ok": True, "out": ""}
 
     def is_repo(path):
         return path in state["repos"]
@@ -162,17 +162,25 @@ def fake_sync_gitops(monkeypatch):
             state["repos"].add(dest)
         return state["ok"], state["out"]
 
-    def pull_ff(cwd, env=None):
-        state["pull"].append({"cwd": cwd, "env": env or {}})
+    def fetch(cwd, env=None):
+        state["fetch"].append({"cwd": cwd, "env": env or {}})
         return state["ok"], state["out"]
 
+    def set_default_head(cwd, env=None):
+        return True, ""
+
+    def default_branch_ref(cwd):
+        return None
+
     def config_local(cwd, key, value):
         state["config"].append({"cwd": cwd, "key": key, "value": value})
         return True, ""
 
     monkeypatch.setattr(gitops, "is_repo", is_repo)
     monkeypatch.setattr(gitops, "clone", clone)
-    monkeypatch.setattr(gitops, "pull_ff", pull_ff)
+    monkeypatch.setattr(gitops, "fetch", fetch)
+    monkeypatch.setattr(gitops, "set_default_head", set_default_head)
+    monkeypatch.setattr(gitops, "default_branch_ref", default_branch_ref)
     monkeypatch.setattr(gitops, "config_local", config_local)
     return state
 
@@ -192,7 +200,7 @@ def test_cmd_sync_clones_then_pulls(env, fake_sync_gitops):
 
     result = worker.execute_command(command)
     assert result["action"] == "pulled"
-    assert fake_sync_gitops["pull"][0]["cwd"] == "/tmp/r"
+    assert fake_sync_gitops["fetch"][0]["cwd"] == "/tmp/r"
 
 
 def test_cmd_sync_failure_is_command_error(env, fake_sync_gitops):

tests/test_reposync_git.py

@@ -0,0 +1,85 @@
+"""``sync_project`` against real git repos — the fetch-not-pull regression.
+
+A pull only moves whichever branch the root has checked out; with the root parked on
+an agent's feature branch, ``origin/*`` went stale and every branch cut for a new
+agent started several commits behind the remote's default branch. These tests use a
+filesystem remote (no host, no credentials) so the git behaviour itself is exercised.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+import pytest
+
+from handler.control import reposync
+
+
+def _git(cwd, *args):
+    subprocess.run(["git", "-C", str(cwd), *args], check=True, capture_output=True)
+
+
+def _sha(cwd, ref="HEAD") -> str:
+    return subprocess.run(
+        ["git", "-C", str(cwd), "rev-parse", ref],
+        check=True, capture_output=True, text=True,
+    ).stdout.strip()
+
+
+@pytest.fixture
+def remote_and_root(tmp_path):
+    """An origin repo, a clone of it as the project root, then origin moves ahead."""
+    origin = tmp_path / "origin"
+    origin.mkdir()
+    _git(origin, "init", "-q", "-b", "main")
+    for repo_dir in (origin,):
+        _git(repo_dir, "config", "user.email", "t@t.co")
+        _git(repo_dir, "config", "user.name", "t")
+        _git(repo_dir, "config", "commit.gpgsign", "false")
+    _git(origin, "commit", "-q", "--allow-empty", "-m", "one")
+    root = tmp_path / "proj"
+    subprocess.run(
+        ["git", "clone", "-q", str(origin), str(root)], check=True, capture_output=True
+    )
+    _git(root, "config", "user.email", "t@t.co")
+    _git(root, "config", "user.name", "t")
+    _git(root, "config", "commit.gpgsign", "false")
+    _git(origin, "commit", "-q", "--allow-empty", "-m", "two")
+    return origin, root
+
+
+def _project(origin, root) -> dict:
+    return {"id": "p", "root_dir": str(root), "git_remote": str(origin)}
+
+
+def test_sync_refreshes_origin_even_when_root_parked_on_agent_branch(
+    env, remote_and_root
+):
+    origin, root = remote_and_root
+    _git(root, "checkout", "-q", "-b", "agent/old-work")
+    # Simulate a clone that never had origin/HEAD — sync must re-pin it too.
+    _git(root, "remote", "set-head", "origin", "-d")
+
+    result = reposync.sync_project(_project(origin, root))
+
+    assert result["action"] == "pulled"
+    assert _sha(root, "origin/main") == _sha(origin, "main")
+    assert _sha(root, "refs/remotes/origin/HEAD") == _sha(origin, "main")
+    # The parked checkout itself is left alone — only origin/* moves.
+    assert _sha(root, "HEAD") != _sha(origin, "main")
+
+
+def test_sync_fast_forwards_a_checkout_sitting_on_the_default_branch(
+    env, remote_and_root
+):
+    origin, root = remote_and_root
+    result = reposync.sync_project(_project(origin, root))
+    assert result["action"] == "pulled"
+    assert _sha(root, "HEAD") == _sha(origin, "main")
+
+
+def test_sync_fails_loudly_when_the_default_branch_diverged(env, remote_and_root):
+    origin, root = remote_and_root
+    _git(root, "commit", "-q", "--allow-empty", "-m", "local divergence")
+    with pytest.raises(reposync.SyncError, match="fast-forward"):
+        reposync.sync_project(_project(origin, root))

tests/test_worktree.py

@@ -31,6 +31,36 @@ def repo(tmp_path):
     return root
 
 
+@pytest.fixture
+def cloned(tmp_path):
+    """A root cloned from an origin whose main has since moved on.
+
+    Mirrors the spawn-time state after ``reposync.sync_project``: origin/* is fresh
+    (fetched), but the root's checkout still sits on the older commit.
+    """
+    origin = tmp_path / "origin"
+    origin.mkdir()
+    _git(origin, "init", "-q", "-b", "main")
+    _git(origin, "config", "user.email", "t@t.co")
+    _git(origin, "config", "user.name", "t")
+    _git(origin, "config", "commit.gpgsign", "false")
+    _git(origin, "commit", "-q", "--allow-empty", "-m", "one")
+    root = tmp_path / "proj"
+    subprocess.run(
+        ["git", "clone", "-q", str(origin), str(root)], check=True, capture_output=True
+    )
+    _git(origin, "commit", "-q", "--allow-empty", "-m", "two")
+    _git(root, "fetch", "-q", "origin")
+    return root
+
+
+def _sha(cwd, ref="HEAD") -> str:
+    return subprocess.run(
+        ["git", "-C", str(cwd), "rev-parse", ref],
+        check=True, capture_output=True, text=True,
+    ).stdout.strip()
+
+
 def _is_worktree(root, path) -> bool:
     out = subprocess.run(
         ["git", "-C", str(root), "worktree", "list", "--porcelain"],
@@ -54,6 +84,30 @@ def test_creates_branch_when_it_does_not_exist(repo):
     assert "feat/new-thing" in branches
 
 
+def test_new_branch_is_cut_from_remote_default_not_root_head(cloned):
+    # The regression: new agent branches were cut from the root's HEAD, so a checkout
+    # sitting behind (or parked on an earlier agent's branch) produced branches several
+    # commits behind origin's default branch.
+    target = worktree.resolve_working_dir(
+        str(cloned), "agent", worktree_branch="feat/fresh"
+    )
+    assert _sha(target) == _sha(cloned, "origin/main")
+    assert _sha(target) != _sha(cloned, "HEAD")
+
+
+def test_new_branch_from_remote_default_gets_no_upstream(cloned):
+    # --no-track: without it the new branch adopts origin/main as upstream, and the
+    # agent's plain `git push` would aim at the default branch.
+    target = worktree.resolve_working_dir(
+        str(cloned), "agent", worktree_branch="feat/fresh"
+    )
+    upstream = subprocess.run(
+        ["git", "-C", target, "rev-parse", "--abbrev-ref", "@{upstream}"],
+        capture_output=True, text=True,
+    )
+    assert upstream.returncode != 0
+
+
 def test_checks_out_existing_branch(repo):
     _git(repo, "branch", "feat/existing")
     target = worktree.resolve_working_dir(